Integrations Architecture

The Integrations module is the central integration catalog and connector hub of the Stella Ops release control plane: the single, tenant-scoped place where connections to external tools — SCM providers, container registries, secrets managers, and CI systems — are registered, health-checked, and resolved for downstream modules.

Audience: engineers extending the connector catalog or consuming the integrations API, and operators onboarding external tools. This dossier covers the service runtime, data model, API surface, plugin admission, and the Secret Authority boundary. For the shared plugin runtime see the Plugin Framework architecture.

Overview

The Integrations module provides a unified service for managing connections to external tools (SCM providers, container registries, CI systems). It uses a plugin-based architecture where each external provider is implemented as a connector plugin, enabling new integrations to be added without modifying core logic. All integration state is persisted in PostgreSQL with tenant-scoped isolation.

Mounted connector runtime (updated 2026-06-04). External connector bundles are mounted read-only from devops/plugins/integrations/<profile>/<plugin-id>/ to /app/plugins/integrations/<profile>/<plugin-id>/; config mounts at /app/etc/plugins/integrations, trust roots at /app/trust-roots/plugins/integrations, and scratch/probe output belongs under /var/lib/stellaops/plugin-scratch/integrations. Cloud, proprietary, network-heavy, and SCM/CI provider sets are opt-in profile overlays, not base image payload.

The base mirror/storage connectors that stay in the WebService image are host-owned bootstrap behavior for offline and local registry operations. Their probe rows use profile image, remain visible for diagnostics, and are non-required for mounted-plugin acceptance. Profile-mounted connectors remain required once declared by compose and must pass manifest, signature, load, and probe admission.

Design Principles

1. Plugin extensibility - New providers are added as plugins, not core code changes
2. Credential indirection - Secrets are referenced via AuthRef URIs pointing to external vaults; the integration catalog never stores raw credentials
3. Tenant isolation - Every integration record is scoped to a tenant; queries are filtered at the data layer
4. Health-first - Every integration has a health check contract; the latest probe result is durable on the catalog row

Components

Integrations/
├── StellaOps.Integrations.WebService/             # HTTP API (Minimal API), IntegrationService, plugin loader, secret broker
├── StellaOps.Integrations.PluginHost.ProcessRunner/ # Out-of-process child runner for sandboxed external connectors
├── __Libraries/
│   ├── StellaOps.Integrations.Contracts/          # Shared DTOs, IIntegrationConnectorPlugin, IIntegrationCatalog seam
│   ├── StellaOps.Integrations.Core/               # Enums, IntegrationConfig, lifecycle events, DORA RoI metadata
│   ├── StellaOps.Integrations.Persistence/        # PostgreSQL via IntegrationDbContext + embedded SQL migrations
│   ├── StellaOps.Integrations.Services/           # Cross-host service helpers
│   └── StellaOps.Integrations.DockerV2/           # Docker Registry v2 client primitives
├── __Plugins/                                     # Connector implementation source projects
│   ├── StellaOps.Integrations.Plugin.GitHubApp/   # Profile-bundled GitHub App / GitHub Enterprise connector
│   ├── StellaOps.Integrations.Plugin.GitLab/      # Profile-bundled GitLab Server / GitLab CI connector
│   ├── StellaOps.Integrations.Plugin.Gitea/       # Profile-bundled Gitea SCM connector
│   ├── StellaOps.Integrations.Plugin.Harbor/      # Profile-bundled Harbor registry connector
│   ├── StellaOps.Integrations.Plugin.DockerRegistry/ # Profile-bundled Docker Registry / GitLab Container Registry connector
│   ├── StellaOps.Integrations.Plugin.Jenkins/     # Jenkins CI connector
│   ├── StellaOps.Integrations.Plugin.Nexus/       # Nexus repository connector
│   ├── StellaOps.Integrations.Plugin.Vault/       # HashiCorp Vault secrets-manager connector
│   ├── StellaOps.Integrations.Plugin.Consul/      # Consul config connector
│   ├── StellaOps.Integrations.Plugin.EbpfAgent/   # eBPF runtime-host agent connector
│   └── StellaOps.Integrations.Plugin.InMemory/    # In-memory test double (NOT in the built-in catalog; test fixtures only)
├── __Extensions/                                  # Non-.NET IDE extensions (see "IDE Extensions" below)
│   ├── vscode-stella-ops/                         # VS Code extension (TypeScript)
│   └── jetbrains-stella-ops/                      # JetBrains plugin (Kotlin)
└── __Tests/                                       # xUnit test projects + process-isolation plugin fixtures
    ├── StellaOps.Integrations.Tests/
    ├── StellaOps.Integrations.Plugin.Tests/
    └── StellaOps.Integrations.DockerV2.Tests/

Note: the InMemory connector lives under __Plugins/ but is deliberately excluded from IntegrationBuiltInPluginCatalog.GetAssemblies(); the running WebService never loads it. It is referenced only by explicit test harnesses. Docker Registry / GitLab Container Registry now follows the same runtime-composition rule as the other external connectors: the source project can be built as a signed bundle, but integrations-web does not compile or load it from the image.

Data Flow

[External Tool] <── health check ─────────── [Integrations WebService]
                                                    │
[Client Module] ── GET /api/v1/integrations ──>    │
                                                    │
[Admin/CLI] ── POST /api/v1/integrations ─────>    │ ── [IntegrationDbContext] ── [PostgreSQL]
                                                    │
[Plugin Loader] ── load built-in + admit external ─│ ── [Plugin Framework]

1. Registration: An administrator or automated onboarding flow creates an integration record via POST /api/v1/integrations, providing type/provider, endpoint, optional extendedConfig, and — at most one of — an inline secret (inlineSecret + credentialKind) or an external authRefUri. Registry-typed integrations must carry credentials.
2. Discovery: The IntegrationPluginLoader registers the host-owned provider catalog (WebService-local feed/object-store probes only) and, only when enabled, verifies external directory candidates before retaining provider descriptors in memory for lookup and failure reporting. In production, external directory admission requires signature trust, declared connector capabilities, a healthy stellaops.pluginhost.process.v1 child-runner handshake, and child-runner metadata validation. External DLLs are not loaded into the WebService process; accepted external candidates are exposed as process-backed connector proxies.
3. Health checking: The API invokes each integration’s provider-specific health check and persists the latest result (last_health_status, last_health_check_at) even when the status is unchanged. Background polling ships and is enabled by default: IntegrationHealthMonitor (a BackgroundService registered at Program.cs:407) sweeps every Status==Active && !IsDeleted integration across all tenants via IGlobalIntegrationRepository and calls the same CheckHealthAsync per row. Defaults (IntegrationHealthMonitorOptions, bound from Integrations:HealthMonitor): Enabled=true, Interval=5m (clamped to a floor), InitialDelay=1m. Offline/air-gap note: because health probes are outbound calls to the configured provider endpoints, a sealed site that does not want periodic egress attempts must set Integrations:HealthMonitor:Enabled=false. Health-history tables and alert emission remain target capabilities (the monitor overwrites the latest status and emits IntegrationHealthChangedEvent in-process; it does not append history rows).
4. Consumption: Downstream modules query the catalog filtered by tenant: human/operator callers list via GET /api/v1/integrations?type={type} (there is no /integrations/{type} path segment), and cross-module consumers that hold the integrations data (e.g. Scanner’s bulk-import) resolve a single integration through the in-process read-only IIntegrationCatalog seam rather than HTTP. Release-orchestrator (and Scanner.Worker / SbomService) fetch the credential via POST /api/v1/integrations/{id}/resolve-credentials, which always returns it AEAD-sealed (sealedSecret) and unseal it in memory — no plaintext credential travels on the wire (SPRINT_20260704_002 / CUS-3).
5. Registry auto-scan (Sprint 20260607_001, AUTO-001/004/005): when a registry integration becomes Active (on add/connect, and via a periodic catch-up sweep) its repositories/tags are enumerated, each tag is resolved to its image digest, and a discovery row is appended to integrations.registry_image_discoveries. The Scanner.Worker RegistryImageDiscoveredBridgeService consumes that outbox and submits a readiness-gated scan per digest — so SBOM-readiness auto-populates and the deploy gate stops blocking on missing SBOMs, with no manual POST /api/v1/scans. See “Registry auto-scan” below.

Registry auto-scan (close the SBOM-readiness gap)

RegistryImageEnumerator is provider-aware:

• Generic OCI (DockerHub / registry:2 / Harbor): /v2/_catalog → /v2/{repo}/tags/list → manifest HEAD (Docker-Content-Digest) to resolve the digest, reusing the connector’s Distribution v2 Bearer-challenge dance (StellaOps.Integrations.DockerV2).

• GitLab CE (GitLab Container Registry): the GitLab registry API — GET /api/v4/groups/{group}/registry/repositories (paginated) → GET /api/v4/registry/repositories/{id}/tags → per-tag …/tags/{name} whose detail carries digest. GitLab CE denies /v2/_catalog to non-admin PATs, so the catalog endpoint is never used for GitLab; the group is read from ExtendedConfig.gitlabGroupPath / gitlabGroupId (without it, enumeration is skipped, logged).

• JFrog Artifactory: tries the Docker Registry v2 catalog first. If the Artifactory Docker endpoint returns 404 for _catalog, the connector and auto-scan enumerator fall back to the Artifactory storage API using non-secret ExtendedConfig.artifactoryRepository and/or ExtendedConfig.artifactoryStorageApiBase. The fallback tries the Pro ?list&deep=1&listFolders=0 API first and, when Artifactory OSS returns 400/403, walks the ordinary storage folder tree before continuing through Docker Registry v2 tag and manifest HEAD paths for digest resolution.

Enumeration is bounded (MaxReposPerRegistry, MaxTagsPerRepo), deterministically ordered (repo asc, tag asc), honours ExtendedConfig.scanRepoPattern / scanTagPattern globs, and is fail-soft (a single repo/tag failure is logged and skipped). A registry that is Failed/anonymous/credential-unresolvable is never enumerated (S046-001).

The on-connect path (RegistryAutoScanOnConnectTrigger) is fire-and-forget off the request hot path (a detached scoped task) so it never changes the create/test latency or status. The periodic sweep (RegistryAutoScanSweepService, modelled on RegistryWriteDriftMonitor) enumerates active registries cross-tenant via IGlobalIntegrationRepository.GetActiveByTypeAcrossAllTenantsAsync; it is disabled by default (opt-in) and capped by MaxIntegrationsPerSweep + a global MaxImagesPerSweep so one large registry cannot flood the scan queue (remaining images roll to the next sweep). Dedupe across the on-connect path and the sweep is owned by the Scanner-side deterministic scan id, not by the outbox.

Config keys — service options under Integrations:RegistryAutoScan: Enabled (on-connect default, default true), MaxReposPerRegistry, MaxTagsPerRepo, DefaultRepoPattern, DefaultTagPattern, and Sweep:{Enabled (default false), Interval, InitialDelay, MaxIntegrationsPerSweep, MaxImagesPerSweep}. Per-integration ExtendedConfig overrides: autoScanOnConnect (bool, overrides the service default both ways), scanRepoPattern, scanTagPattern, gitlabGroupPath/gitlabGroupId (GitLab only).

For Artifactory storage API fallback, per-integration ExtendedConfig may include artifactoryRepository and/or artifactoryStorageApiBase; these are non-secret routing hints and are forwarded to the process-isolated connector runner.

Registry provider descriptors and matrix

Registry onboarding is descriptor-driven. StellaOps.Integrations.Core.RegistryProviderDescriptor is the source contract for registry tiles and IRegistryProvider is the marker implemented by registry connector plugins. The descriptor carries the stable descriptorId, provider enum, friendly display name, default endpoint and hint, accepted authModes, discovery strategy, OCI write-probe flag, setup-document link, local test image hint, connector name, and optional cloud token-exchange note.

GET /api/v1/integrations/providers projects these descriptors into ProviderInfo. The console merges that backend metadata onto its presentation definitions keyed by descriptorId, so auth fields and setup links come from the descriptor catalog instead of hard-coded FE guesses. Auth modes are wire-compatible with the existing credential contract: anonymous sends no credential, basic composes username:secret, and token sends the bare bearer/PAT value.

The cloud rows are implemented without AWS, Google, or Azure SDK dependencies. The token endpoints are overrideable so local labs can attempt provider-compatible emulators and so unit tests can assert the exact request/signature shapes. When no provider-compatible emulator or cloud credential is available, the strongest local runtime proof is an authenticated OCI Distribution endpoint using a provider-shaped, already-exchanged Docker-login credential (AWS:<password>, oauth2accesstoken:<token>, or the ACR null-guid username). That proves the Stella Ops descriptor, credential materialization, OCI read, discovery, and auto-scan paths, but it is not AWS/GCP/Azure managed control-plane proof. The S020 retry against the local test-ecr LocalStack container returned HTTP 501 for GetAuthorizationToken, so no ECR managed-control-plane proof is claimed.

The local compose QA fixtures include S020 OCI Distribution services under devops/compose/docker-compose.integration-fixtures.yml with htpasswd files in devops/compose/fixtures/integration-fixtures/registry-providers/. They provide the test-harbor, s020-harbor-registry, s020-dockerhub-oci, s020-ghcr-oci, s020-ecr-oci, s020-gcr-oci, and s020-acr-oci network aliases used by the provider matrix evidence. Seed them with real image manifests before discovery; the S020 proof copied library/alpine:latest from the existing local test-registry-basic:5000 registry. s020-harbor-registry runs the real Harbor registry-photon binary for the OCI Distribution component only. Full Harbor application proof is covered separately in docs/qa/feature-checks/runs/2026-06-23-s020-harbor-full-local-app-proof/: the run pulled official goharbor/prepare:v2.11.0, generated a disposable Harbor v2.11 compose/config under ignored local runtime/, started core/portal/db/jobservice/redis/nginx/registry/registryctl/log, seeded s020/alpine:full-local, and verified Stella Ops Harbor /test, /discover, and image browse against http://host.docker.internal:18085. The committed evidence keeps command output and summaries only; generated DB, key, and test-credential material remains ignored.

Database Schema

PostgreSQL. The default connection string targets database stellaops_integrations, and EF Core / the embedded SQL migrations own the integrations schema (IntegrationDbContext.DefaultSchemaName = "integrations"). Migrations are applied on startup via AddStartupMigrations("integrations", "Integrations.Persistence", …).

Indexes: ix_integrations_type, ix_integrations_provider, ix_integrations_status, ix_integrations_tenant_id, a partial unique index ix_integrations_tenant_name over (tenant_id, name) WHERE is_deleted = false, and a partial ix_integrations_requires_creds_resolution. Delete is soft (is_deleted = true). Migration 004_v1_registry_image_discovery_integration_stamp.sql adds discovery browse indexes on (tenant_id, integration_id, repository_path) and (tenant_id, image_digest) for the registry/image browser read paths.

Tenant-isolation invariant (SPRINT_20260531_035, class C1 fix)

Every read / mutate against integrations.integrations MUST be tenant-scoped. This is enforced in two layers:

1. Application layer (primary defence) — IIntegrationRepository. Every method that touches a tenant-owned row carries a required tenantId parameter that is applied as a WHERE tenant_id = @tenantId predicate in SQL. BuildQuery rejects a null/empty IntegrationQuery.TenantId with ArgumentException (no silent cross-tenant fallthrough). Bypass for genuinely system-wide scans (e.g. health workers) is the explicit IGlobalIntegrationRepository seam, so cross-tenant intent is auditable in DI rather than smuggled through a magic-null id. A cross-tenant UpdateAsync throws IntegrationNotFoundException (mapped to HTTP 404 at the API surface) — never an InvalidOperationException that would leak row existence.
2. Database layer (defence-in-depth) — migration 007_tenant_isolation_rls.sql. PostgreSQL Row-Level Security is enabled (not forced) on integrations.integrations, with a single policy integrations_tenant_isolation keyed on current_setting('app.current_tenant_id', true). Table owners and BYPASSRLS roles continue to bypass per the standard pattern (mirrors release.integrations reference at Migrations/Release/001_IntegrationHub.sql:196), so the migration is safe to land on running services — only future non-owner callers that bypass the repository would meet the policy. The app.current_tenant_id session variable is the same GUC used elsewhere in the platform (see shared.actor_identity in 076_ActorIdentity.sql).

Why both layers? Hunter #1 (multi-tenancy audit, 2026-05-31) confirmed that the application-layer filter had been missing on 7 methods (GetByIdAsync, UpdateAsync, DeleteAsync, GetByProviderAsync, GetActiveByTypeAsync, UpdateHealthStatusAsync, BuildQuery’s optional-tenant fallthrough). For the highest-severity instance — UpdateAsync — tenant A could rewrite tenant B’s config_json/auth_ref_uri/credential_ciphertext columns and trigger health-checks under their own worker simply by knowing the row id. The single-layer fix would have been adequate but would re-expose the same class the next time a caller appears that doesn’t go through the repository wrapper. Belt + braces.

Regression coverage: PostgresIntegrationRepositoryTenantIsolationTests (Testcontainers Postgres, one test per fixed method, asserts returned-row tenant_id matches the caller’s, never != null).

The KEK control plane (crypto.kek_versions) and the credential re-seal progress tables are owned by StellaOps.Cryptography.CredentialStore and registered for this service via AddCryptoKekVersionsMigrations("Integrations") / AddCredentialReSealMigrations("Integrations"); they are shared infrastructure, not Integrations-local tables.

The /internal/crypto/* routes are installation-wide control-plane operations, not tenant catalog APIs. They still require an authenticated principal: reads accept crypto:kek:read, crypto:kek:rotate, or ops.admin; start/abort accept crypto:kek:rotate or ops.admin. Platform forwards a validated operator Bearer token or relays the gateway-signed identity envelope after Platform verified it as StellaRouterEnvelope; Integrations verifies/re-authorizes the identity again. Network bypass alone cannot authorize these routes. Base compose accepts both api://integrations and first-party stellaops audiences and reaches the service on port 8080. The default compose transport remains internal HTTP, so this boundary must not be described as mTLS until direct certificate-bound listeners and clients are provisioned.

DORA Register of Information metadata

Connection profiles can carry optional doraRoiMetadata for DORA Register of Information projections. The metadata is stored as JSONB on the catalog row and is included in create/update/read DTOs so downstream RoI encoders can project integrations without scraping provider-specific configuration.

Fields:

• criticalityLevel with criticalityLevelProvenance.
• contractStartDate with contractStartDateProvenance.
• contractEndDate with contractEndDateProvenance.
• subContractingChain[], where each entry has rank, providerName, optional providerIdentifier, optional ISO 3166-1 alpha-2 countryCode, and provenance.

Provenance is explicit. operatorFilled is valid for operator-entered fields and all deeper subcontracting ranks. autoCapturedDepth1 is valid only for the direct provider at subContractingChain.rank == 1; ranks greater than 1 must remain operator-filled. This implements the approved DORA-Q3 decision that Stella auto-discovers only direct integrations and must not imply automatic knowledge of deeper supply chains.

The Web Integration Hub treats this as optional module metadata, not as a global product mode. During integration onboarding, operators can opt in to attach DORA RoI metadata on the discovery-scope step. The Console sends scalar criticality and contract-date fields with operatorFilled provenance, allows autoCapturedDepth1 only for rank-1 subcontracting rows, forces deeper ranks to operatorFilled, and shows stored metadata read-only on the integration overview. Profiles without RoI metadata remain unchanged.

The shipped schema does not include module-owned health_checks, audit_logs, or plugin_metadata tables. The service persists the latest health result on integrations; mutable endpoint audit is emitted through the shared unified audit pipeline and structured service logs. Historical health retention and an Integrations-local audit store require separate schema work.

Endpoints

Registry browse endpoints are additive under /api/v1/integrations/registries, require tenant context, and use Integration.Registry.Read -> registry:read (StellaOpsScopes.RegistryRead).

All endpoints below are mapped under the /api/v1/integrations group in IntegrationEndpoints.cs. The group requires authorization and a tenant context (RequireAuthorization(IntegrationPolicies.Read).RequireTenant()), and each route additionally pins a per-operation policy. The three policies map to canonical scopes: Integration.Read → integration:read, Integration.Write → integration:write, Integration.Operate → integration:operate (see Program.cs AddStellaOpsScopePolicy wiring and StellaOpsScopes.IntegrationRead/Write/Operate). Route IDs use {id:guid} constraints.

Integration CRUD (/api/v1/integrations)

• GET / — List integrations for the current tenant. Query parameters: type, provider, status (enums), search, page (default 1), pageSize (default 20), sortBy (default name), sortDescending (default false). Defined numeric enum values remain accepted for operator compatibility (type=5 is RuntimeHost); undefined numeric values are rejected with a sealed RFC-7807 400 rather than being treated as valid empty filters. Returns a PagedIntegrationsResponse (items, totalCount, page, pageSize, totalPages). Scope: integration:read.
• GET /{id} — Get integration by ID. 404 outside the caller’s tenant scope. Scope: integration:read.
• POST / — Register a new integration. Request body carries exactly ONE of inlineSecret (with credentialKind) OR authRefUri, or neither for a genuine no-credentials integration. The inlineSecret/authRefUri pair is mutex-validated server-side and the resulting row lands in one of three canonical shapes (see “Credential backends” below). Registry-typed integrations registered without any credential are rejected with HTTP 400 anonymous_registry_not_allowed (AnonymousRegistryNotAllowedException). When a connector plugin exists for the provider, the service auto-runs a test connection and may flip the row to Active/Failed. Returns 201 Created. Scope: integration:write.
• PUT /{id} — Update integration configuration (same credential-shape and registry-credential rules). An update that touches neither credential field leaves the existing backend untouched. Scope: integration:write.
• DELETE /{id} — Soft-delete the integration (is_deleted = true) with audit; returns 204 No Content (or 404). Scope: integration:write.

Operations

• POST /{id}/test — Run an on-demand provider test-connection, update status (Active/Failed) when it changes, and emit a test/integration.test_connection audit event. Returns TestConnectionResponse. Scope: integration:operate.
• POST /{id}/discover — Discover provider resources for a resourceType (e.g. repositories, projects, pipelines, jobs, tags). Body: { resourceType, filter? }. Returns 200 (DiscoverIntegrationResponse), 404 (not found), 400 (unsupported resource type, with supportedResourceTypes), or 502 on connector failure. Scope: integration:operate.
• POST /{id}/resolve-credentials — Trusted in-cluster only. Resolves the credential and always returns it AEAD-sealed — no plaintext credential ever travels on the wire (SPRINT_20260704_002 / CUS-3). ResolveIntegrationCredentialsResponse: integrationId, credentialBackend, credentialKind, resolvedAt, and sealedSecret (the sealed envelope; null when the integration resolves to no credential material). Every consumer (release-orchestrator’s HttpRegistryCredentialResolver, Scanner.Worker, and SbomService) unseals sealedSecret in memory and fails closed when the envelope or response-domain KEK is absent. The former plaintext secret member and consumer downgrade branches have been physically removed. A legacy ?seal=true query flag is harmless but ignored because sealing is unconditional. The secret is never logged or written to the audit row. Scope: integration:operate.
• GET /{id}/impact — Static impact map: which downstream workflows are affected by this integration’s status, with severity, blockingWorkflowCount, and impactedWorkflows[]. Scope: integration:read.
• POST /ai-code-guard/run — Standalone AI Code Guard run (AiCodeGuardRunRequest: owner, repo, commitSha, optional configYaml, files[]). Scope: integration:operate.

Registry browse (/api/v1/integrations/registries)

• GET /api/v1/integrations/registries - Tenant-scoped registry posture over persisted discovery rows. Returns RegistryPostureResponse[] with integrationId, display name, registryHost, nullable slug, imageCount, repositoryCount, lastDiscoveredAt, evaluatedImages, nullable criticalCount, nullable highCount, and nullable reachabilityPosture. A discovery summary with no active tenant-scoped integration is omitted before digest security lookup; the remaining rows preserve discovery order. Integration metadata is loaded in one tenant-scoped registry query rather than one lookup per summary. Security fields are projected through IRegistryImageVulnStateProvider by digest; the default NullRegistryImageVulnStateProvider returns no rows, so nullable fields mean genuinely unevaluated rather than fabricated zero findings. Scope: registry:read.
• GET /api/v1/integrations/registries/{id}/images - Tenant-scoped keyset-paginated discovery rows for one registry integration. Query parameters: pageSize (default 50, capped at 200) and afterId (default 0). Returns RegistryImagePagedResponse with page-local totalCount, nextAfterId, and items carrying repository/tag/digest plus both presentation references: maskedRef (stella+oci://registries/<slug-or-guid>/repo@digest) and realRef (host/repo@digest). Each image row also carries nullable legacy security fields (criticalCount, highCount, mediumCount, sbomReadiness, reachabilityPosture, hasDecision, verdict, lastScanAt) plus additive Scanner v2 fields (readiness, scanStatus, lastAttemptAt, lastSuccessfulScanAt). A missing provider row leaves those fields null to preserve honest unevaluated state. A registry id outside the caller tenant returns 404. Scope: registry:read.

When a Scanner storage connection string can be resolved from ScannerStorage:Postgres:ConnectionString, ConnectionStrings:Default, or ConnectionStrings:IntegrationsDb, the WebService registers ScannerRegistryImageVulnStateProvider instead of the policy-only fallback. Only this Scanner-DSN branch registers IScanRuntimeStateRepository, IArtifactBomRepository, and the validated Scanner:SbomReadiness:SuccessfulScanMaxAge option (positive, default 14.00:00:00). The read-only provider joins the latest runtime attempt, latest durable BOM, public reachability verdicts, severity counts, and policy decision by tenant + image digest. Per-digest Scanner reads execute with a fixed concurrency bound (ScannerRegistryImageVulnStateProvider.MaxConcurrentDigestLookups) and results are reassembled in requested-digest order; this prevents database-latency multiplication without allowing unbounded connection fan-out. Durable BOM age maps to v2 readiness=ready|stale; a successful lookup with no BOM maps to absent. Exact attempt aliases map to pending, running, succeeded, failed, or cancelled, with the attempt timestamp kept separate from lastSuccessfulScanAt. A BOM-only row remains visible. Legacy sbomReadiness and lastScanAt retain their previous attempt-derived mapping byte-for-byte. A non-cancellation durable-BOM repository failure is logged and degrades only v2 readiness to null (unknown/unavailable), while runtime attempt, policy, severity, and reachability enrichments remain usable; request cancellation still propagates.

Policy gate decisions are joined through a separate read-only adapter over policy.gate_decisions, resolved from PolicyStorage:Postgres:ConnectionString, Policy:Postgres:ConnectionString, ConnectionStrings:PolicyDb, ConnectionStrings:Default, or the Integrations connection string fallback. The adapter resolves tenant slugs through shared.tenants, sets app.current_tenant_id, and reads the latest row per lower-cased image_digest by evaluated_at/decision_id. Policy statuses map to registry-browser verdicts as pass/allow -> allow, warn/review -> warn, and fail/block/deny -> block; unknown statuses remain unknown. When Scanner storage is unavailable, PolicyOnlyRegistryImageVulnStateProvider still exposes hasDecision=true and verdict for matching digest rows while scan and reachability fields stay null. This is an explicit short-term cross-domain read projection for the image browser; a future signed OCI referrer or Policy-owned projection may supersede it without changing the browser response shape.

Credential backends (explicit, post-Sprint-032)

Every integration row carries an explicit credentialBackend discriminator in one of three canonical shapes. The legacy credential_backend='none' + non-null auth_ref_uri shape was removed in Sprint 032 (no released version carried it); registration rejects it with HTTP 400 and migration 005 backfilled any residual rows to authref.

Resolution dispatch is unified across both code paths (IntegrationService.BuildConfigAsync for test/health/discover, and IntegrationCredentialResolver.ResolveAsync for release-orchestrator’s sync-versions): both run the same explicit-backend switch with no default back-compat dispatch. Release-orchestrator’s HttpRegistryCredentialResolver always dispatches to integrations-web’s /resolve-credentials (the none-backend short-circuit was removed in Sprint 032 because it defeated the integrations-web back-compat for sync-versions).

DB invariant: ck_integrations_credential_backend CHECK constraint (migration 005) rejects any row that doesn’t match one of the three shapes above. ADR-004 forward-only; downgrade is via PostgreSQL snapshot restore.

Health (/api/v1/integrations)

• GET /{id}/health — Trigger an on-demand provider health check, return its current result (HealthCheckResponse), and persist the latest status/timestamp (last_health_status, last_health_check_at) on the integration row via UpdateHealthStatusAsync, even when unchanged. Emits an IntegrationHealthChangedEvent only when the status actually transitions. When no plugin is available or the connector lacks the integration:health-check capability, the result is Unknown. Scope: integration:read.

Runtime health

• GET /health
• GET /health/liveness
• GET /health/readiness

All three runtime aliases call the same IntegrationHealth handler and return { status: "Healthy", timestamp }. They are anonymous (AllowAnonymous) container/orchestrator probes and do NOT trigger provider checks; provider health remains under /api/v1/integrations/{id}/health.

Provider discovery

• GET /providers — List the connector providers loaded into the current WebService process (ProviderInfo[]: name, type, provider, isTestOnly, supportsDiscovery, supportedResourceTypes). Optional ?includeTestOnly=true includes the InMemory test provider (excluded by default). There is no public endpoint that mutates plugin discovery state. Scope: integration:read.

JSON wire shape (request + response)

Sprint SPRINT_20260528_033 (commits 6cb43f2711 + a3a7384bab) restored the legacy operator contract for enum fields on POST/PUT /api/v1/integrations:

• Enum fields (type, provider, status) accept BOTH string and INT representations. The minimal-API JSON pipeline registers JsonStringEnumConverter with CamelCase naming and allowIntegerValues=true, so all four wire shapes below resolve to the same enum member:

  Shape	Example	Notes
  PascalCase	"type": "Scm", "provider": "GitLabServer"	The conventional name in the StellaOps.Integrations.Core.IntegrationEnums source. Preferred for human-readable operator scripts (01-register-integrations.ps1).
  camelCase	"type": "scm", "provider": "gitLabServer"	Matches OpenAPI-generated typed clients and the convention used by sibling services (Concelier, PacksRegistry).
  lowercase	"type": "scm", "provider": "custom"	Common when shell-env values are forwarded unchanged (type=$TYPE etc.).
  INT	"type": 2, "provider": 201	Back-compat with Sprint 029 FIX-003’s 01b-register-inline-integrations.sh. The INT values come from IntegrationEnums.cs (Scm=2, GitLabServer=201, …).

  Operator preference: string-PascalCase is recommended for new scripts (matches the source-of-truth enum names and is stable across future enum-member additions). INT representation is fragile — inserting a new enum member in the middle of the numeric range shifts subsequent values and silently breaks operator scripts.

• HTTP 400 responses carry an RFC-7807 ProblemDetails body. Validation failures (malformed JSON, unknown enum value, mutex violations) return a JSON body shaped like:

  {
    "type": "https://stella-ops.local/probs/bad-request",
    "title": "Invalid request",
    "status": 400,
    "detail": "The request body or parameters are invalid.",
    "traceId": "00-58ccc5c6691828d01577ee0e26d37e32-2d50cfb62ddcf182-00",
    "service": "integrations"
  }
  

  The traceId lets operators correlate the 400 with the request trace. The service field is always "integrations". The detail field is stable host-authored text; handled binder and parser exception diagnostics are suppressed and never returned because they can contain submitted values.

• HTTP 500 responses do not expose exception details. Unexpected server failures return a stable generic detail; the exception message, stack, and inner exceptions are not serialized to the caller. Operators correlate the failure with server-side type-only logging through the response traceId. This boundary applies even when the service is reachable only on an internal network, because downstream exceptions can contain credentials, connection strings, remote payload fragments, or host paths.

• Empty 400 bodies are a regression. Prior to Sprint 033 the minimal-API binder returned 400 with Content-Length: 0, giving operators zero debugging signal. If you see an empty 400 body on this service, the Sprint 033 image has not rolled — file a follow-up rather than reverting the operator script to INT enums.

Bulk SCM import

Sprint SPRINT_20260514_001 adds a bulk import primitive so an operator can onboard an entire SCM org in one call. The endpoints live in the Scanner WebService (not Integrations), because the work product is a fan-out of SBOM source registrations + scan triggers:

• POST /api/v1/scm/{integrationId}/bulk-import - body {repos: [{name, cloneUrl, branch?}], maxConcurrent}. Validates that {integrationId} resolves to an SCM-typed integration, registers one Git SBOM source per repo, triggers a scan per source, and returns 202 {batchId, repoCount, status}. A single repo failing (CreateAsync / TriggerScanAsync) is isolated and never aborts the batch.
• GET /api/v1/scm/imports/{batchId} - per-repo status + counts (succeeded / failed / pending), the live inFlight gauge, and the maxConcurrent cap. Returns 404 for unknown batches.

IIntegrationCatalog seam

Scanner.WebService references StellaOps.Integrations.Contracts only - not Persistence / WebService. To classify an integration without a write-side dependency, Contracts now exposes a read-only IIntegrationCatalog (GetIntegrationAsync(id) / IsScmIntegrationAsync(id)). The Postgres-backed IntegrationCatalog implementation lives in StellaOps.Integrations.Persistence and is registered by hosts that own the integrations data (AddIntegrationCatalog()). Scanner.WebService registers a fail-safe NullIntegrationCatalog default via TryAddSingleton, so a host wiring the real catalog wins; on its own the bulk-import endpoint fails closed (404) rather than fanning out against an unverified integration.

Throttling

Concurrency is bounded by an in-process SemaphoreSlim sized to maxConcurrent (clamped to [1, 64], default 8). The batch lifecycle and the in-flight gauge are tracked in an in-memory BatchStatusStore. A Valkey-backed distributed throttle is a future sprint - the Scanner test host strips the Valkey subscriber, so in-process is the correct default today.

CLI

• stella scm import --integration <id> --file repos.txt --max-concurrent 20 reads a TSV repo list (name<TAB>cloneUrl[<TAB>branch]), POSTs the bulk endpoint, polls every 5s until terminal, and exits 0 only when every repo succeeded.
• stella scm import-status --batch <id> is a one-shot batch status read.
• stella scm list-repos is blocked pending a connector contract: IIntegrationConnectorPlugin exposes DiscoverAsync but no ListRepositoriesAsync. Adding that method (and implementing it across the GitHubApp / GitLab / Gitea plugins) is tracked for a follow-up sprint.
• stella scan submit-list --file scan-list.txt --max-concurrent 20 triggers a scan for each already-registered SBOM source id, throttled the same way.

Plugin Architecture

Each connector plugin implements IIntegrationConnectorPlugin (in StellaOps.Integrations.Contracts), which extends the shared IAvailabilityPlugin:

public interface IIntegrationConnectorPlugin : IAvailabilityPlugin
{
    IntegrationType Type { get; }
    IntegrationProvider Provider { get; }
    Task<TestConnectionResult> TestConnectionAsync(IntegrationConfig config, CancellationToken ct = default);
    Task<HealthCheckResult> CheckHealthAsync(IntegrationConfig config, CancellationToken ct = default);
}

(IAvailabilityPlugin supplies Name and an availability gate; there is no ProviderType string or ValidateConfigAsync method.) Discovery-capable connectors additionally implement IIntegrationDiscoveryPlugin (SupportedResourceTypes, DiscoverAsync). Connectors that gate operations declare IIntegrationConnectorCapabilityDeclaration.DeclaredCapabilities over the capability ids integration:test-connection, integration:health-check, integration:discovery, integration:discovery:<resourceType>, and integration:credential-materialization (IntegrationConnectorCapabilities).

IntegrationConfig (the value passed to connectors) carries IntegrationId, Type, Provider, Endpoint, ResolvedSecret (plaintext, resolved per-backend by IntegrationService.BuildConfigAsync), OrganizationId, ExtendedConfig, and SecretRefUri (set instead of ResolvedSecret for process-isolated connectors).

Image-resident connectors (the canonical set currently registered via IntegrationBuiltInPluginCatalog.GetAssemblies()):

• DockerRegistry / GitLabContainerRegistry — OCI Distribution connector. This is a signed/profile-mounted connector bundle, not an image-resident WebService dependency.
• Feed-mirror and object-storage probes registered from the WebService assembly itself; see FeedMirrorConnectorPlugins / ObjectStorageConnectorPlugins.

Profile-bundled connectors:

• GitHubApp — GitHub App / GitHub Enterprise Server authentication, repository/code-scanning discovery.
• GitLab — GitLab Server / GitLab CI access-token authentication, project discovery.
• Gitea — Gitea SCM connector.
• Harbor — Harbor robot-account authentication, project/repository enumeration.
• Jenkins, Nexus, Vault, Consul, and the eBPF Agent remain optional/profile connector packages.

Profile-bundled connectors are not WebService project references. They must be supplied as signed directory bundles before the production provider list exposes them.

The current generated bundle profiles are:

• recommended: stellaops.integrations.vault, stellaops.integrations.harbor, stellaops.integrations.githubapp, and stellaops.integrations.dockerregistry.
• harness: stellaops.integrations.inmemory only.
• integrations-scm-ci: stellaops.integrations.gitea, stellaops.integrations.jenkins, stellaops.integrations.nexus, and stellaops.integrations.gitlab.
• secrets-optional: stellaops.integrations.consul.
• runtime-host: stellaops.integrations.ebpfagent.

There is no base executable Integrations bundle in this slice. S3-compatible object storage and feed mirror providers stay host-owned until a future migration explicitly externalizes them.

InMemory is a deterministic test double for explicit test harnesses. It is NOT part of the built-in catalog and the default WebService runtime does not load it (GetSupportedProviders(includeTestOnly) filters it out unless explicitly requested).

External connector plugin admission

The production WebService does not treat a DLL in Integrations:PluginsDirectory as a valid connector by filename alone.

• Image-resident connectors are loaded from IntegrationBuiltInPluginCatalog and are governed by normal Stella Ops build provenance.
• Optional connector bundles use a directory-local manifest named stellaops.integration-plugin.json. The manifest schema version is 1 and declares id, SemVer version, relative assembly, providers[] (type, provider, aliases[]), capabilities[], detached signature.path, trustRoots[], and profiles[].
• Bundle manifests fail closed before runner metadata is trusted when required capability declarations are missing. Baseline connector bundles must declare integration:test-connection and integration:health-check; discovery connectors must also declare integration:discovery or a resource-specific integration:discovery:<resourceType> capability; connectors that need authref/brokered credential materialization can declare integration:credential-materialization.
• Integrations:PluginProfileRoots adds profile-mounted bundle roots without changing the legacy base directory. Existing roots are loaded in deterministic path order, and each root’s final path segment must be present in every bundle manifest’s profiles[]; a mismatch is rejected as bundle_profile_mismatch.
• External directory plugins are disabled by default with Integrations:PluginAdmission:EnableExternalDirectoryPlugins=false.
• If candidate DLLs are present while external directory loading is disabled, startup fails explicitly instead of silently accepting or ignoring potentially untrusted code.
• Startup validation fails when external directory loading is enabled unless Integrations:PluginAdmission:EnforceSignatureVerification remains true and a local trust root is configured (PublicKeyPath, CertificatePath, or CertificateIdentity plus CertificateOidcIssuer). File-backed trust material must exist at startup.
• In Production, startup validation additionally requires Integrations:PluginAdmission:ProcessIsolationProvider=stellaops.pluginhost.process.v1, ProcessIsolationRunnerPath, and a successful runner handshake. The provider starts the configured child process and expects a deterministic JSON readiness payload before startup validation succeeds.
• The process-v1 provider also defines a deterministic JSON operation IPC envelope with per-invocation timeout/kill behavior and a bounded stdout/stderr output policy (ProcessIsolationMaxOutputBytes, default 65536 bytes per stream). Over-limit handshake or operation output kills the child runner and fails closed with sandbox_runner_output_limit_exceeded or sandbox_operation_output_limit_exceeded before IPC output is trusted. Dead runner paths such as missing runners, early exit before a response, malformed operation responses, timeout kills, and malformed runner-health state return deterministic lifecycle evidence (runner.lifecycleState, started/timed-out/output-limit flags, request id, and exit code when known) with pluginCodeExecuted=false. The host can also enforce configured supervised operation budgets (ProcessIsolationOperationCpuTimeBudgetMilliseconds and ProcessIsolationOperationPrivateMemoryBudgetBytes): it samples the direct child runner process CPU time and private memory, kills on budget breach, and fails closed with sandbox_operation_cpu_budget_exceeded or sandbox_operation_memory_budget_exceeded. This is not an OS/kernel hard limit and does not supervise a process tree. The shipped runner accepts runner-health and connector metadata operations, and can execute integration:test-connection, integration:health-check, and integration:discovery operations for a connector loaded inside the child process when the operation allowlist permits them. Responses include pluginCodeExecuted=true and runner process evidence.
• When process isolation is required, the loader verifies the candidate signature, asks the child runner to read connector metadata and capability declarations, and registers a process-backed proxy. The WebService process does not call Assembly.Load for the external DLL.
• The default connector operation allowlist enables integration:test-connection, integration:health-check, and integration:discovery. Authref-backed calls for those operations require a broker grant; other connector operations require explicit allowlist support and implementation.
• Verification uses the shared plugin signature verifier. The default Cosign verifier expects a detached .sig beside each connector assembly and defaults UseRekorTransparencyLog=false so offline and air-gapped deployments do not call public transparency services.
• Directory-loaded connectors must implement IIntegrationConnectorCapabilityDeclaration and declare at least integration:test-connection and integration:health-check; discovery-capable connectors must also declare integration:discovery.
• The loader wraps declaring connectors in a capability-enforcing proxy before adding them to the registry. Test-connection, health, and discovery calls obtained from IntegrationPluginLoader fail closed when the required capability is absent, without resolving secrets or calling the plugin operation. IntegrationService keeps its own pre-invocation checks as a second guard.
• Rejected plugins are not instantiated, cannot report successful test-connection results, and are surfaced through loader failure metadata.
• The current Integrations WebService provides a child-runner readiness boundary, process-backed metadata validation, process-backed integration:test-connection, process-backed integration:health-check, and process-backed integration:discovery execution.
• For process-backed connectors, IntegrationService does not resolve the catalog row’s authRefUri while constructing the generic operation request. It passes only an opaque authref handle in the process-v1 secretReferences[] field plus a broker grant when a broker is configured. The generic IPC payload, process args, process environment, and response evidence intentionally omit both the authref URI and resolved secret value.
• Authref-backed directory-loaded connector operations now use a host-owned per-operation named-pipe secret broker. The WebService creates a one-use grant bound to request id, operation, opaque handle, and TTL (ProcessIsolationSecretBrokerTtlMilliseconds, default 5000 ms). The child runner connects to that channel, presents the grant, and receives the resolved secret only after broker authorization; connector code executes only after materialization succeeds. Missing, expired, replayed, malformed, or unauthorized grants fail closed with deterministic broker error codes and pluginCodeExecuted=false.
• The process-v1 host enforces per-invocation timeout/kill, stdout/stderr output ceilings, deterministic dead-runner/lifecycle evidence, configured supervised CPU/private-memory operation budgets, process discovery execution, and brokered single-authref materialization. Kernel-enforced CPU/memory limits, long-lived lifecycle supervision, restart policy, process-tree accounting, platform-specific named-pipe/Unix-socket peer identity ACLs, durable broker audit event routing, and multi-secret operations remain follow-up work.

This keeps test-only connectors such as InMemory out of production discovery and prevents unsigned external connector binaries from becoming production-valid integration evidence.

Provider endpoint contracts

• GitHub App - Operators provide either the GitHub Cloud root (https://github.com), a GitHub Enterprise Server root, or an explicit /api/v3 base. The connector normalizes the endpoint to a single API root and probes relative app / rate_limit paths so GitHub Enterprise onboarding never falls back to origin-root /app.
• Harbor - Operators provide the Harbor registry base URL. The current registry connector is descriptor-driven and uses the OCI Distribution v2 surface (/v2/, _catalog, tag lists, manifest HEAD) for connection tests, discovery, and image enumeration. The deterministic harbor-fixture.stella-ops.local nginx fixture only serves Harbor API-shaped /api/v2.0 responses; it is useful for retained API-onboarding checks but is not sufficient for the registry provider matrix because it does not expose /v2/. The s020-harbor-registry fixture runs Harbor’s registry component and proves that OCI surface. Full Harbor core/portal/database/jobservice behavior is now covered by the S020 full local app proof in docs/qa/feature-checks/runs/2026-06-23-s020-harbor-full-local-app-proof/.
• Docker Registry / GitLab Container Registry - Operators provide the registry base URL. When the registry responds with WWW-Authenticate: Bearer ..., the connector exchanges the configured secret against the advertised token realm and retries with the returned bearer token. The local GitLab registry uses authref://vault/gitlab#registry-basic, storing username:personal-access-token.

Secret Authority

The Integrations service now exposes a provider-agnostic Secret Authority boundary for onboarding flows that need to stage credential material before creating an integration.

Goals

• Keep raw secrets out of the integration catalog.
• Let UI and CLI stage credentials once and receive authref://... bindings in return.
• Audit secret bundle creation/update separately from integration CRUD.
• Fail truthfully when a secrets-manager provider is visible but not writable in this release.

API surface (/api/v1/secret-authority)

• GET /targets
  • Lists tenant-visible secrets-manager integrations that can be used as staging targets.
  • Returns integration metadata only: integrationId, name, provider, endpoint, status, logicalPathHint, supportsWrite.
• PUT /bundles/{bundleId}
  • Stages or updates a credential bundle in the selected target.
  • Request body: targetIntegrationId, optional logicalPath, entries[], optional labels, overwrite.
  • Response returns only metadata plus generated authrefs:
    • bundleId
    • logicalPath
    • authRefs
    • target provider and endpoint

Current writer support

• Vault KV v2 is the first shipped writer.
• Other secrets-manager providers remain visible in discovery, but write attempts fail explicitly with 501 not_implemented.
• For Vault targets, the service writes directly to the target secret engine and returns authrefs such as:
  • authref://vault/gitlab/server#access-token
  • authref://vault/gitlab/registry#registry-basic

Security model

• Read policy: integration:read via IntegrationPolicies.SecretAuthorityRead
• Write policy: integration:write via IntegrationPolicies.SecretAuthorityWrite
• Secret bundle writes emit the upsert_secret_bundle audit action in the Integrations audit module.
• The API never echoes raw secret values back to the caller.

UI / CLI usage

• The Web Integrations Hub uses Secret Authority for inline GitLab Server, GitLab CI, and GitLab Container Registry onboarding.
• The CLI exposes the same flow through:
  • stella config integrations secrets targets
  • stella config integrations secrets upsert-bundle --bundle <id> --target <integration-id> --entry key=value
• Integration create/update operations persist either an authRefUri (when the operator selects the authref backend) or an AEAD-sealed inlineSecret (when the operator selects the inline backend). The two are mutex; see “Credential backends” above. For authref rows the secret bundle and authref lifecycle are owned by the secret-authority target, not by the catalog row. For inline rows the catalog row carries the sealed ciphertext directly (see StellaOps.Cryptography.CredentialStore.CredentialAead).

Security Considerations

Public error-disclosure boundary

Integrations classifies failure text by origin; authentication alone does not make arbitrary provider text safe to return:

Successful authenticated connector probes may retain bounded operational facts: HTTP status codes; normalized operation.success, operation.healthStatus, and operation.durationMs; typed runner.* lifecycle counters/states; boolean broker/materialization evidence; secret-reference counts/kinds; and explicitly redacted secret-leak proof fields. Arbitrary plugin detail keys and plugin-authored failure messages are not part of the public contract. Correlation uses the HTTP trace identifier and stable error code, not raw exception text.

The WebService enforces this boundary after every in-process or process-isolated test-connection and health result. Connector-authored messages, endpoint/path details, remote payload fragments, and write-probe prose are replaced or dropped before response, event, audit, or persisted probe-state projection; plugins cannot opt out of the host sanitizer. Top-level health status is restricted to defined HealthStatus values (unknown values become Unknown), and last_health_check_at is stamped from the host clock so a connector cannot poison monitor scheduling with a future timestamp.

• Explicit credential backend: Every integration row carries an explicit credentialBackend (inline | authref | none). The legacy none + non-null auth_ref_uri back-compat shape was dropped in Sprint 032; registration rejects it with HTTP 400 and the DB CHECK constraint enforces canonical shape on every write.
• AuthRef URI credential model (authref backend): Credentials are stored in an external vault (e.g., HashiCorp Vault, Azure Key Vault). The integration catalog stores only the URI reference (authref://vault/path/to/secret), never the raw secret.
• Inline credential model (inline backend): Credentials are stored Stella-managed in the catalog row, AEAD-sealed via StellaOps.Cryptography.CredentialStore.CredentialAead with per-row (kek_id, kek_version, algorithm) triple. KEK lifecycle is governed by crypto.kek_versions (Sprint 028). The trusted in-cluster resolve-credentials endpoint requires integration:operate and returns only a response-domain AEAD envelope; it never emits, persists, or logs resolved plaintext. Canonical operator workflow: devops/agents-targets/scripts/customer-onboarding/01b-register-inline-integrations.sh (Sprint 029 FIX-003).
• Tenant scoping: All database queries include a mandatory tenant filter enforced at the DbContext level via query filters.
• Audit emission: Create, update, delete, test, discovery, AI Code Guard, and secret-authority operations emit shared audit events and structured logs with actor/resource context. The Integrations module does not currently own a durable audit-log table.
• Plugin admission: Image-resident connectors run from the WebService catalog. Directory-loaded connector DLLs require startup-valid signature enforcement and local trust material, and production external directory admission requires a healthy stellaops.pluginhost.process.v1 runner handshake plus child-runner metadata validation. Declaring external connectors are exposed through a process-backed capability proxy. The default connector operations that can execute across the child-runner boundary are integration:test-connection, integration:health-check, and integration:discovery; authref-backed process operations receive only opaque handles and a one-use broker grant in generic IPC, then materialize plaintext through the broker inside the child runner after authorization. The process-v1 host enforces per-invocation timeout/kill, bounded stdout/stderr capture, deterministic dead-runner evidence, configured sampled CPU/private-memory budget kills, and response-detail redaction for materialized secret values, while broader execution still waits on long-lived lifecycle supervision, restart policy, process-tree/kernel resource controls, platform-specific broker channel ACLs, and durable broker audit routing.

Observability

• Metrics: The Integrations WebService does not currently register a dedicated Meter/counters of its own. (Earlier drafts listed integration_health_status, integration_health_latency_ms, and integration_crud_total — those metric instruments do not exist in the source; treat them as a target, not shipped behavior.) Request-level telemetry comes from the shared host/router instrumentation, not from module-local instruments.
• Audit: CRUD, test, discover, AI Code Guard, resolve-credentials, and secret-bundle operations emit shared unified-audit events (AuditModules.Integrations, actions Create/Update/Delete/Test/Discover/RunCodeGuard/ResolveCredentials, plus upsert_secret_bundle) via IAuditEventEmitter, in addition to a IIntegrationAuditLogger structured-log trail. The resolve-credentials audit records backend + kind metadata only, never the secret value.
• Logs: Structured logs include integrationId, tenantId/tenant scope, Provider, and the action verb.
• Lifecycle events: IntegrationService publishes in-process lifecycle events through IIntegrationEventPublisher (created/updated/deleted/status-changed/health-changed/test-connection/RoI-metadata-changed); the default publisher is a logging implementation (LoggingEventPublisher).

Performance Characteristics

• Health checks run on demand through GET /api/v1/integrations/{id}/health and on the default-on background sweep (IntegrationHealthMonitor, every Integrations:HealthMonitor:Interval, default 5 min, first sweep after a 1 min InitialDelay). The sweep is best-effort — a per-integration failure is caught and never aborts the pass — and cost scales with the number of active integrations across all tenants. Set Integrations:HealthMonitor:Enabled=false to disable periodic outbound probing.
• Registry-image security enrichment retains its fixed per-digest Scanner lookup concurrency inside one request, while a process-wide outer gate admits one enrichment request at a time. This prevents concurrent registry pages from multiplying the inner database fan-out across requests; pagination and the nullable/unevaluated response contract are unchanged.
• Plugin loading happens once at startup (IntegrationPluginLoader loads the image-resident catalog and, if enabled and admitted, external directory candidates) and the resulting provider registry is held in memory for the process lifetime. There is no runtime re-discovery endpoint.
• Integration queries are backed by the indexes on tenant_id, type, provider, and status (see Database Schema) for tenant-scoped filtering.

IDE Extensions (VS Code, JetBrains)

The Integrations module also owns the IDE extension plugins, located under src/Integrations/__Extensions/. These are non-.NET projects intended to provide developer-facing tooling consuming the Orchestrator/Router APIs.

Status: these extensions are early skeletons, not yet wired to live backend APIs. As shipped, the VS Code extension is a single src/extension.ts providing tree-view scaffolding and a configurable backend URL (default https://localhost:5001); it does not yet issue the /api/v1/releases/*, /api/v1/promotions/*, or /oauth/token calls described in “Data Flow (Extensions)” below — that flow is the target design. The JetBrains plugin ships StellaOpsPlugin.kt but does not include a committed Gradle wrapper. Treat the feature lists and data flow below as planned scope.

VS Code Extension (__Extensions/vscode-stella-ops/)

• Technology: TypeScript, VS Code Extension API
• Build: npm run compile (TypeScript compilation)
• Features: Tree views for releases and environments, CodeLens annotations for stella.yaml, command palette integration, status bar widget
• Manifest: package.json (extension manifest, commands, views, configuration)

JetBrains Plugin (__Extensions/jetbrains-stella-ops/)

• Technology: Kotlin, IntelliJ Platform SDK
• Build: Gradle (./gradlew build)
• Features: Tool windows (Releases/Environments/Deployments tabs), YAML annotator, action menus, status bar widget
• Entry point: StellaOpsPlugin.kt

Design Principles (Extensions)

1. Thin client - Extensions contain no business logic; all state and decisions live in backend services
2. Consistent experience - Both plugins expose equivalent functionality despite different technology stacks
3. Non-blocking - All API calls are asynchronous; the IDE remains responsive during network operations
4. Offline-tolerant - Graceful degradation when the Stella Ops backend is unreachable

Data Flow (Extensions)

[Developer IDE] --> [Extension/Plugin]
                         |
                         +-- GET /api/v1/releases/* --------> [Orchestrator API]
                         +-- GET /api/v1/environments/* ----> [Orchestrator API]
                         +-- POST /api/v1/promotions/* -----> [Orchestrator API]
                         +-- POST /oauth/token -------------> [Authority]

Authentication uses OAuth tokens obtained from the Authority service, stored in the IDE’s secure credential store (VS Code SecretStorage, JetBrains PasswordSafe).

References

• Module README
• Plugin Framework Architecture
• Scanner Architecture