AI Secure Gateway & Prompt Optimizer (SDK)

Central Connect AI SDK is the shared connection layer of the Central Connect AI suite for Drupal: it links any Drupal site to a central services platform operated by a service provider — a digital agency, hosting company or managed-services vendor — over a single, SSRF-hardened OAuth2 channel. It is the foundation that the suite's AI, support and monitoring modules depend on, providing credentials handling, token caching, a canonical endpoint registry, a shared AI gateway, a suite-wide notification framework and a common front-end design system. Install it as a dependency of the consumer modules, or build your own central against the expected API.

What it is

The model is simple: the provider operates one central, issues OAuth2 client_credentials to each connected client site, and every site that installs the suite talks to that central through this SDK — one central, many connected sites, one shared and hardened communication layer. The SDK is intentionally provider-agnostic: it is not tied to a single vendor's platform, so any provider can expose the expected API on their own central and use the suite as their client-facing support, assistance and monitoring stack, or chain to an upstream central and resell its services under their own brand.

Most of the SDK is back-end plumbing — the services, contracts and value objects the rest of the suite consumes — but it also ships the suite's shared notification center and the shared front-end libraries.

Key features

• OAuth2 client — a client_credentials client (CentralOAuth2Client) with a private token cache and automatic token refresh on 401 responses, so connected sites stay authenticated without manual intervention.
• Private token caching — bearer tokens are cached in a dedicated private cache bin (cache.central_connect_ai_sdk) so they never reach shared cache backends.
• Endpoint and scope registry — a canonical registry of the central API endpoint paths and OAuth2 scopes, so consumer modules never hard-code URLs or scopes.
• SSRF-hardened URL validation — every outbound URL is validated through Ssrf::safeOrigin() before any request is made, protecting each call against server-side request forgery.
• Shared AI gateway — AI never runs in the client. Modules relay each operation through AiGatewayInterface to the central, which selects the model per tenant, meters cost and holds the provider keys, returning structured results and typed failures (such as credit_exhausted).
• Premium entitlements resolver — EntitlementProviderInterface / EntitlementsClient report the install's tier, unlocked feature keys and metered limits from the central, cache them and fail closed to the free tier so a feature stays locked when it cannot be verified. This drives UX only; the central enforces access server-side.
• Suite-wide notification framework — modules declare notifications as CcaiNotificationType plugins; the SDK owns the notification entity, the dispatcher, per-user channel preferences, the preferences screen and a shared notification bell. Two channels are provided: in-app (the bell, refreshed by polling) and email (via the Mail Manager / Symfony Mailer).
• Shared icon system — bundled Phosphor duotone SVG icons rendered inline through the ccai_icon() Twig function (and the Drupal.ccai.icon() JS companion), so every module in the suite shares the same glyphs.
• Lightweight summary client — a one-shot LLM client for short summaries, plus shared integration contracts (CostGateInterface, LlmSummarizerInterface) and a suggestions/feedback client with server-side sanitisation and link hardening.
• Shared front-end foundations — design tokens, modal dialogs, toasts, skeleton loaders, an icon picker, a feedback modal, a header component, the AI usage meter and cost modal, plus CSRF-aware fetch/escape/poll helpers, all under the Drupal.ccai namespace.

How it works

The site connects to the central once, and the SDK owns that connection for the whole suite. From Administration » Configuration » Web services » Central Connect AI SDK you set the central base URL and press Connect to provision the site. This is a challenge-based bootstrap: the central fetches a /.well-known file served by the module to verify domain ownership, then issues the OAuth2 client id and secret. The issued client id and secret are stored in State — the secret is never shown in the UI and never exported with configuration — and consumer modules never store their own credentials; they read the shared connection from the SDK. The optional one-shot summary LLM client reads its API key from settings.php (with a State fallback), again never exported with configuration.

Front-end design system

Rather than re-implementing patterns, suite modules attach shared libraries under Drupal.ccai: design tokens (--ccai-* custom properties), modal and confirm dialogs, toasts, skeleton loaders, a searchable icon picker, the feedback modal, visibility-aware polling and the ccai-header Single Directory Component that renders one identical suite header everywhere. The AI usage meter turns a header action into a progress ring that fills as the user spends their AI cost allowance, and the cost modal shows a monthly budget limiter with a per-system spend breakdown and a per-department sub-breakdown, all relayed to the central as the single source of truth.

Part of the Central Connect AI suite

Central Connect AI SDK is the foundation of the Central Connect AI suite. It is the shared dependency that the suite's consumer modules build on for credentials handling, token caching, URL validation and the shared service contracts:

• AI Ticket Chat — an AI-assisted support ticketing and help-desk board where client requests are triaged, valued in hours and reported, with notifications and AI delivered through this SDK.
• Multi-Role AI Chatbot — a floating, role-aware AI assistant for visitors, clients and staff, with per-audience prompts, visibility rules and budgets.
• Web Health Status — a site-owner dashboard that unifies activity, sales, leads, support and AI-assisted insights, using the SDK's shared header, notifications and usage meter.

Requirements

• Drupal — compatible with Drupal 10.3+ and Drupal 11, requires PHP 8.1 or higher.
• No extra modules — this module requires no modules outside of Drupal core.
• Central credentials — to use the OAuth2 services you need client credentials (base URL, client id and client secret) issued by the operator of the central your site connects to. The optional summary LLM client additionally requires an API key.

Privacy and security

Security is built into the connection layer: every outbound request passes SSRF-hardened URL validation, the OAuth2 secret and any API key live in settings.php or State and are never exported with configuration, and bearer tokens are isolated in a private cache bin. Because AI never runs in the client, the central holds the provider keys, selects models and meters cost, and the premium entitlements resolver fails closed to the free tier — the central always remains the security boundary, enforcing access and AI spend server-side.

Maintainers and sponsor

Developed and maintained with sponsorship from Tangram Consulting. Contributions, issues and feature requests are welcome through the project's issue queue on drupal.org.