Connection Hub: One Broker for Delegated Trust

KDCube applications live at a busy intersection of identities. A person signs in. Their agent reaches out to Gmail or Slack. An external automation reaches back in through REST or MCP. A channel actor arrives from Telegram and needs a deliberate link to the platform account that owns its roles and spend.

Connection Hub is KDCube's connection and authority plane. It registers authority providers, verifies request proofs, stores identity edges, brokers connected accounts, issues delegated credentials, and projects the right actor, grantor, identity scope, and economics subject into the runtime. Applications declare what they expose and what they need; the platform performs the trust work before business code runs.

Three directions, three authority objects — a session, provider claims, and resource grants — around one governance plane.

                    PLATFORM AUTHORITY
  accepted upstream proof -> KDCube platform session -> platform subject

       DELEGATED TO KDCUBE                 DELEGATED BY KDCUBE
  platform user -> provider account    platform user -> delegated credential
                -> external service                  -> KDCube resource
       approved provider claims              resource grants + operations

Three directions of trust

The word "connection" covers three journeys. Their direction determines which system issues the credential and which authority the runtime may project.

Platform authority establishes the KDCube user

A provider registered under an authority marked platform: true can establish a KDCube platform subject. KDCube supports Cognito, multi-Cognito, SimpleIDP, and application-hosted platform authority flows. Connection Hub owns the authority/provider registry; deployment configuration selects the active provider.

An application-hosted flow may render the login page and receive an upstream proof such as a Google ID token. The registered platform-session provider verifies that proof, resolves the configured grants, and issues the standard KDCube platform session. A successfully authenticated platform subject with an empty role set receives the baseline kdcube:role:registered role.

This preserves an important distinction: Google supplies upstream proof in that example; kdcube.platform supplies the platform authority. Browser clients use the provider-neutral /api/cp-frontend-config contract and treat /profile as the logged-in-state source of truth.

Delegated to KDCube lets KDCube use a provider account

An external provider issues a credential so KDCube can act inside that provider for the current platform user. Gmail, Slack, iCloud Mail, and a custom OAuth/OIDC service all fit this direction.

The user connects a concrete account. Tools and named services declare the provider claims they need. At execution time, trusted SDK code resolves an eligible account and provider credential through Connection Hub. The model, browser, and tool arguments carry account references and results while provider tokens remain in the server-side user-secret lifecycle.

Delegated by KDCube lets an operator enter KDCube

KDCube issues a bounded credential so an external actor can call a protected KDCube resource for a grantor user. A CI job may call a REST operation. Claude Code or another MCP client may call a managed MCP surface. A signed-in user chooses resources, grants, and operations, then revokes the resulting access from Connection Hub.

The external client remains the actor. The approving platform user remains the grantor and, where policy says so, the economics subject. Runtime projection keeps both facts so product code can use the grantor's authorized scope while audit and provenance still identify the delegate.

These three journeys share one governance plane and use different authority objects: a platform session, a provider account with approved claims, or a delegated-client grant record.

Channel identity connects through an explicit edge

A verified channel actor starts as its own identity. Telegram initData, for example, proves a subject such as telegram:<id> through a non-platform request authenticator. A Connection Hub link flow then lets the user connect that actor to a platform identity.

Telegram Mini App initData
  -> verify Telegram actor
  -> start Connection Hub link challenge
  -> browser obtains a KDCube platform session
  -> user approves the relationship
  -> store telegram:<id> -> platform:<subject> connection edge
  -> future Telegram requests resolve through the edge when required

The actor identity remains visible after projection. A Telegram-facing feature can keep Telegram-scoped storage and provenance, while a platform boundary can use the linked subject's roles, permissions, ownership, and economics identity. The connection edge carries the selected delegation grants that define which projection is available.

This same shape works for Slack channels, WhatsApp, partner applications, and other verified external identities. Link and unlink operate on the relationship itself; the provider proof and platform account remain separate identities.

The connection edge is the relationship — provenance stays with the Telegram actor; roles and economics project from the linked platform subject.

Delegated to KDCube: connected accounts

The outbound direction is modeled in three layers. The separation lets an operator configure a provider once, lets many users connect accounts, and keeps each user's approvals and credentials scoped to that account.

Provider, connector app, connected account — and account metadata stored separately from the user-scoped provider secrets.

Layer	What it declares	Who owns it
Provider	OAuth/OIDC endpoints, profile mapping, provider scopes, and KDCube claim-to-scope mapping	Deployment configuration
Connector app	OAuth client id, secret reference, callback behavior, enabled state, allowed-claim ceiling, and optional claim tiers	Platform operator
Connected account	Provider subject, account/workspace label, approved claims, credential health, and credential reference	One platform user

A provider claim is the KDCube consent unit for an outbound provider action. For example:

gmail:send          -> Gmail provider scopes needed to send mail
slack:history       -> Slack provider scopes needed to read channel history
slack:files:write   -> Slack provider scopes needed to upload a file
s1:read             -> custom S1 scope such as s1.read

The connector app sets the maximum claim ceiling. A tool asks for the concrete subset required by its operation. User-facing claim tiers such as Read, Write, or Files can group those claims without changing the underlying enforcement.

Trusted integration code resolves claims through the SDK. It can request a specific account_id, receive a labeled choice when several accounts qualify, refresh a provider credential once after an authentication rejection, and return a managed reconnect action when the provider still rejects it. Agents receive account references, structured results, files, and consent instructions rather than raw provider credentials.

The attempt is the ask

Connected-account consent is demand-driven. Claim-gated tools remain available to the agent because the turn cannot predict which operation will be useful. At the first attempt, the SDK checks exactly the claims declared for that tool and returns one structured needs_connected_account_consent envelope when the current account state cannot satisfy them.

Reason	Meaning	Repair action
`connect_required`	An eligible account has not been connected	Connect the provider account
`claim_upgrade_required`	The account exists and needs additional claims	Approve the named claims
`reconnect_required`	The provider credential needs renewal	Reconnect that account
`account_required`	Several accounts qualify	Choose a labeled `account_id`

The envelope includes the provider, connector app, exact claims, labeled account candidates when needed, a retry hint, and an absolute Connection Hub action URL. Chat renders the same demand as a consent card with two exits: complete the requested connection step, or turn off the tools that require it. The failed attempt stays scoped to one provider, claim set, and tool instead of expanding into the union of every configured integration.

When the user approves from an active conversation, the approval is recorded as a conversation event. A live turn can fold that event and continue; otherwise the next turn receives the connected-account update as context.

Standard OAuth/OIDC services reuse the broker

The generic oauth2.generic and oidc.generic adapters cover providers with standard OAuth/OIDC mechanics. The operator supplies endpoints, profile mapping, claim-to-scope mapping, connector credentials, and callbacks. This removes the need for a provider-specific authentication adapter. The application or named service still implements the provider's domain API operations, such as searching S1 records or updating an S1 object.

Delegated by KDCube: automation and protected surfaces

The inbound direction has two user journeys and one enforcement model:

Delegated Access creates a short-lived bearer token directly for a script, job, or automation.
Delegated OAuth gives an external client dynamic registration, authorization, consent, code exchange, refresh, and bearer validation.

OAuth is the external protocol adapter. The Connection Hub delegated credential record is the authorization model. Every delegated external client uses the same credential identity:

authority_id       = delegated_client
authenticator_id   = delegated_client.bearer
credential_kind    = delegated_client_access
audience           = kdcube:delegated_client

The bearer string is an opaque handle. Connection Hub hashes it, loads the server-side access-grant and session records, and derives authority from the matching resource_grants entry plus selected operations.

{
  "resource_grants": {
    "https://runtime.example/api/records": ["records:read"],
    "https://runtime.example/api/tasks": ["tasks:read", "tasks:write"]
  },
  "operations": ["records_export", "task_list", "task_update"],
  "identity_scope": "grantor_identity_family"
}

Grant checks stay inside the matched resource. tasks:write on the tasks resource adds no write authority to records. The wildcard resource "*" is a real policy entry used for all-resource admin automation and carries the configured kdcube:role:super-admin grant.

The bearer is a handle; the server-side record holds the authority. The managed guard resolves and projects before any product code runs.

An application protects its own REST or MCP surface with managed credentials. The descriptor declares the protected resource and operation/tool requirements. The managed guard performs bearer verification, resource matching, operation narrowing, grant projection, and identity/economics projection before the handler runs. Product code receives the projected runtime context and keeps its focus on the operation itself.

external client
  -> Authorization: Bearer <opaque handle>
  -> delegated_client.bearer authenticator
  -> server-side access-grant lookup
  -> match request resource
  -> enforce selected operation and matching grants
  -> project delegate actor + grantor/economics subject
  -> call application handler

MCP is one protected resource transport. REST is another. The same Connection Hub authorization model protects both, while MCP presents operations as tools at its protocol edge.

When an external agent reaches a provider: two gates

The two delegation directions meet when an external agent uses a KDCube named service backed by a connected provider account. The call crosses two explicit authorization gates.

External MCP agent
  |
  | Gate 1: delegated-by-KDCube resource and namespace grants
  |         named_services:use + slack:read / slack:write
  v
KDCube named-service gateway
  |
  | Gate 2: delegated-to-KDCube connected-account claims
  |         slack:history / slack:files:write / slack:post
  v
User's connected Slack account
  |
  v
Slack API

Gate 1 answers: may this external client use this KDCube resource and operation? Examples include mail:read, mail:send, slack:read, and slack:write.

Gate 2 answers: may KDCube perform this provider action through this user's connected account? Examples include gmail:read, gmail:send, slack:history, slack:files:read, and slack:post.

The grants and claims remain separate records because they protect different boundaries. Passing Gate 1 gives the agent access to a KDCube namespace. Passing Gate 2 gives KDCube permission to call the external provider for the current user. A missing Gate 2 approval returns the same structured consent/reconnect contract through MCP that chat uses.

A delegated credential is a consent snapshot. Its resources, namespaces, operations, and grants reflect what the user approved at issuance. Publishing a new namespace in runtime configuration leaves existing credentials unchanged; the external connector requests updated consent to receive the wider snapshot.

Two boundaries, two records — resource grants at the KDCube gate, provider claims at the account gate; a delegated credential is a consent snapshot.

Where authority and secrets live

Connection Hub uses several storage surfaces intentionally. Each record lives where its lifecycle and sensitivity fit.

Record	Storage role
Authority providers, connector apps, claim catalogs, resource policy	Application descriptors and configuration; secret references only
OAuth client secrets and deployment credentials	Platform secrets lifecycle
Connected-account metadata and credential health	User-scoped account metadata under Connection Hub application storage
Provider access/refresh tokens and app passwords	User-scoped secrets
Delegated-client access grants and session records	Server-side Redis grant/session stores, resolved fail-closed by managed guards
Connection edges and link challenges	Connection Hub edge/challenge storage

Application storage is filesystem-backed: local or mounted storage in local runtimes and normally shared EFS in cloud deployments. Artifact storage is a separate API that may use local filesystem or object storage. Connected-account metadata can say that a token exists and report its health; provider token bytes live in user-scoped secrets.

The split produces precise revocation behavior:

Disconnecting a connected account removes KDCube's usable provider credential for that account.
Managing account access replaces the approved provider-claim set after provider reapproval.
Revoking delegated access invalidates its server-side grant/session records, so the previously issued bearer handle stops resolving.
Unlinking a channel identity removes the connection edge, so future channel requests retain their external actor identity without that platform projection.

One UI can present these actions together while each one changes the exact relationship the user selected.

What an application builder declares

Connection Hub removes repeated protocol and storage work while leaving the application's product decisions explicit.

Builder declares	Connection Hub and the runtime enforce
Which registered platform provider a deployment uses	Proof verification, platform session issue/verification, role baseline, browser auth contract
Which provider and claims a tool or named service requires	Account selection, claim coverage, credential health, refresh/reconnect, consent action
Which REST/MCP resources, operations, and grants an external client may receive	Consent narrowing, token issue, server-side grant lookup, managed guard, actor/grantor projection
Which channel authenticator and link flow an external identity uses	Proof verification, challenge approval, connection edge, authority/economics projection

Application code uses SDK resolvers and projected runtime identity. It defines domain operations, tool behavior, and product policy while the platform owns credential parsing, token storage, consent protocol, and cross-surface enforcement.

Why it is one system

Connection Hub centralizes governance without collapsing the underlying concepts. Platform authority establishes a KDCube subject. Connection edges relate independently verified identities. Provider claims let KDCube reach out through a user's account. Resource grants let a delegated actor reach in to a KDCube resource. Managed guards and SDK resolvers enforce those facts at the boundary where they matter.

Consider one Slack request from an external agent:

1. The agent presents a KDCube delegated-client bearer handle.
2. The managed MCP guard resolves its server-side resource grants.
3. The named-service gateway checks slack:read or slack:write.
4. The Slack realm resolves the grantor user's connected account.
5. The provider-claim broker checks slack:history, slack:post, or file claims.
6. Slack receives the call through the server-side user credential.
7. The result returns with delegate provenance and grantor/economics identity.

Each boundary has one answerable question, one record of consent, and one revocation path. Applications gain integrations and delegated operators without placing provider secrets, platform session logic, or bearer-token authority in their business handlers.