Skip to content

AIFACTORY-FEAT-033: IntegrationService: thin delivery for the first outcome

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.

A design artefact, not a tracker

This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).

Epic Integration Platform (PF-06) · Increment I1 Generate a microservice · State elaborated · Route backend-developer · Build order 71 of 185 (Factory code)

IntegrationService is the service of bounded context BC-16 (Connections). Tenant-scoped connections to external systems — provider, endpoint policy, credential references (never values), grants that say which projects, agents and tools may use a connection, rotation metadata and health — with every use brokered as a short-lived credential by the Secret Broker (BC-16). In this increment it is delivered thin: One Azure DevOps connection per project with its credential reference. Its own repository is ConnectSoft.AI.SoftwareFactory.IntegrationService.

Delivers IntegrationService (thin): One Azure DevOps connection per project with its credential reference.
Stubs —
Realizes adrs: ADR-0015, ADR-0019, ADR-0022
Requirements FR-01, FR-05, FUX-01, FUX-02, NFR-02, NFR-03, XL-10, XL-13
Depends on —
Sources model/services/integration/IntegrationService.yaml

Scenarios to trace (11, catalog): SCN-IntegrationService-001 ✓, SCN-IntegrationService-002 ✓, SCN-IntegrationService-003 ✓, SCN-IntegrationService-004 ✓, SCN-IntegrationService-005, SCN-IntegrationService-006, SCN-IntegrationService-007 ✓, SCN-IntegrationService-008 ✓, SCN-IntegrationService-009 ✓, SCN-IntegrationService-010 ✓, SCN-IntegrationService-011

AIFACTORY-US-067: IntegrationService answers the chain with its thin contract

behavior · persona workspace-admin As a workspace admin, I want one Azure DevOps connection for my project, registered with its credential reference, verified, granted to the project and resolved for the services that use it, so that the chain reads template feeds and opens the change proposal through a connection whose credential no service ever holds.

This is the integration PBI of the thin delivery. The thin scope stated in model/backlog/features/integration.yaml is one Azure DevOps connection per project with its credential reference, and the delivery holds exactly that: a Workspace admin or Platform admin registers a connection of provider Azure DevOps with its credential kind and its Key Vault reference (AIFACTORY-US-1004), lists the connections of the tenant (AIFACTORY-US-1005), verifies the credential through the Secret Broker, which activates the connection (AIFACTORY-US-1006), and grants the connection to the project (AIFACTORY-US-1007); the services of the chain resolve the connection of a project with its grant check through the internal gRPC method Connections.Resolve (AIFACTORY-US-1008), ToolAdapterService for the change proposal and ConnectorRegistryService for the capabilities of its connector, which it resolves for the template feeds of TemplateRegistryService under the template-feed project of the platform tenant and for the certification under the sandbox project. Nothing else is served. The platform bundle allows a connection grant, the action kind connection-grant, for a Workspace admin of the project and the Platform admin (D127, D129), so on a deployed I1 instance a Project grant is written for those callers and refused for every other. RotateCredential, RevokeConnection, the event CredentialRotated, the transitions to Suspended and Revoked, the workers ConnectionHealthProbe and RotationReminder and the handlers of ProjectStateChanged, SecretRotated and SecretReferenceRevoked arrive with feature integration-service-complete in I5; the handler of DeletionOrderIssued is built in I4 with RetentionResidencyService and is not registered here. Until then a revoked secret reference is refused by the Secret Broker when a caller exchanges its ticket, so no outbound call is made without a brokered credential (fail closed). The repository ConnectSoft.AI.SoftwareFactory.IntegrationService is created and scaffolded in I0 by AIFACTORY-TASK-089 of feature repository-and-pipeline-conventions (D140), by the steps of its repository checklist, and this feature starts from that scaffold; it was scaffolded once from the pinned base template package with UseFactoryProfile (features component-base-template-factory-profile and component-base-template-findings, consumed by their pinned versions), so token validation, the scope chain with its 401, 403 and 404 answers, the tenant row filter, health, readiness and the telemetry wiring come from the profile. The messaging profile is the Orleans profile under the service name integration; the service writes the run event envelope of the contracts package through the Orleans outbox in the transaction of its command, for ConnectionRegistered, ConnectionStateChanged and ConnectionGrantChanged and for the audit evidence event AuditEvidenceSubmitted on the topic audit.evidence.v1.evidence-submitted of the pinned audit library, and the thin delivery registers no consumed event. A user token reaches the service with the audience of its own gateway, IntegrationHost, which the service accepts (ADR-0015 amendment D117); a workload token carries service scopes and no tenant claim. A connection stores a credential reference and its kind, never a value: no request, row, event, receipt, log record, activity or metric holds a secret value, and the service never holds a credential, also not during a verification (ADR-0019). The credential reference is held in the row and in the broker ticket of Connections.Resolve only, which the caller presents to the Secret Broker; it never appears in a list reply, an event, an audit evidence record, a log record, an activity or a metric. The REST operations are public routes of the IntegrationHost gateway, delivered in I1 like the other gateways (D127, D129), and the delivery builds no direct public route; a Workspace admin or Platform admin provisions the connection of a project on a deployed I1 instance by the runbook of AIFACTORY-TASK-4070 through that gateway.

Acceptance criteria

AC1 Given the repository ConnectSoft.AI.SoftwareFactory.IntegrationService created and scaffolded in I0 by AIFACTORY-TASK-089 of feature repository-and-pipeline-conventions, whose first commit is the unchanged output of dotnet new connectsoft-base -n ConnectSoft.AI.SoftwareFactory.IntegrationService --UseFactoryProfile true from the pinned template package, when its pipeline runs with the work of this feature, then the solution builds, the unit and acceptance tests pass with complete reports and a container image is published (ADR-0028, model/services/integration/IntegrationService.yaml).
AC2 Given the service descriptor of the thin delivery, when the contract test of the Factory profile compares it with the hosted surface, then exactly IntegrationService/RegisterConnection, IntegrationService/ListConnections, IntegrationService/VerifyConnection, IntegrationService/SetGrant and IntegrationService/Connections.Resolve are hosted, as AIFACTORY-US-1004 to AIFACTORY-US-1008 prove one by one, the paths of RotateCredential and RevokeConnection answer 404, and the test fails when an operation outside the thin scope stated in model/backlog/features/integration.yaml appears (ADR-0022).
AC3 Given the integration messaging profile, when its registration is inspected, then the outbox publishes IntegrationService/ConnectionRegistered, IntegrationService/ConnectionStateChanged, IntegrationService/ConnectionGrantChanged and the audit evidence event under the run event envelope of the pinned contracts package in the transaction of their commands, no consumed event is registered, the handler of DeletionOrderIssued included, and no other event of the model is declared (ADR-0012, docs/reference/schemas/run-event-envelope.schema.json).
AC4 Given a call without a token, without a workload identity or without the scope of the operation, or a workload call that forwards no tenant, when it reaches one of the five operations, then it is refused before any handler runs and nothing is read (ADR-0015); given the service starts, then liveness answers and readiness is unready until integration-sql is migrated and the identity authority is reachable; given the captured requests, rows, events, logs, activities and metrics of the acceptance suite, then none holds a secret value or a token (ADR-0019).
Traces: services IntegrationService
Traces: aggregates IntegrationService/Connection
Traces: apis IntegrationService/RegisterConnection, IntegrationService/ListConnections, IntegrationService/VerifyConnection, IntegrationService/SetGrant, IntegrationService/Connections.Resolve
Traces: events IntegrationService/ConnectionRegistered, IntegrationService/ConnectionStateChanged, IntegrationService/ConnectionGrantChanged
Traces: descriptors run-event-envelope-v1, audit-evidence-v1, execution-scope-v1
Traces: adrs ADR-0012, ADR-0015, ADR-0019, ADR-0022, ADR-0028
Traces: requirements FR-01, FR-05, NFR-02
Depends on AIFACTORY-US-1004, AIFACTORY-US-1005, AIFACTORY-US-1006, AIFACTORY-US-1007, AIFACTORY-US-1008, feature:repository-and-pipeline-conventions, feature:component-base-template-factory-profile, feature:component-base-template-findings, feature:contracts-package, feature:component-audit-factory-evidence, feature:component-observability-factory-conventions
Sources model/services/integration/IntegrationService.yaml, model/backlog/features/integration.yaml, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md, docs/architecture/adr/0019-data-governance.md, docs/planes/capability-tools/connectors/services/integration-service/index.md#purpose-and-responsibilities

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-090 Host the thin surface: five operations behind scope policies, the messaging profile with three published events and the deployment values implementation RegisterConnection, ListConnections, VerifyConnection, SetGrant and Connections.Resolve are hosted with the scope policies of the Factory profile and the Idempotency-Key filter of RegisterConnection and VerifyConnection; the integration messaging profile publishes ConnectionRegistered, ConnectionStateChanged, ConnectionGrantChanged and the audit evidence event under the run event envelope of the pinned contracts package and registers no consumed event; the deployment manifest states the replica range 2 to 8, the probes, the base addresses of SecretBrokerService, PolicyEngineService and ProjectService, the secret reference messaging-transport by name and never by value, Integration:Connections:DefaultRotationDays and Integration:Connections:VerifyOnActivate at their modelled defaults, and no setting names the action kind of a grant, which is fixed in the service (D129); the three metrics of model/services/integration/IntegrationService.yaml are registered with their modelled dimensions. ConnectSoft.AI.SoftwareFactory.IntegrationService
AIFACTORY-TASK-091 Contract of the thin surface: service descriptor, OpenAPI document of the four REST operations and proto of Connections.Resolve contract The service descriptor file lists exactly RegisterConnection, ListConnections, VerifyConnection, SetGrant and Connections.Resolve with path or method, scope, side-effect class and idempotency as model/services/integration/IntegrationService.yaml states them; the OpenAPI document fixes the registration body without any member for a credential value, the list, the verification result and the grant; the proto fixes the provisional reply message of AIFACTORY-TASK-4052; a contract test with golden files holds the shapes and compares the hosted endpoints with the descriptor file in both directions, so callers run against this service without a fake. ConnectSoft.AI.SoftwareFactory.IntegrationService
AIFACTORY-TASK-4070 Provisioning runbook of the Azure DevOps connection of a project on a deployed I1 instance, inside the cluster and without a public route documentation The repository documentation holds the runbook by which a Workspace admin or Platform admin provisions the connection of a project through the IntegrationHost gateway of I1 (D129), for a project of a tenant and for the sandbox project and the template-feed project of the platform tenant: it calls the public routes of the gateway, never the cluster-internal address of the service, with a user token of the authorization server whose one audience is IntegrationHost, the audience the service accepts (ADR-0015 amendment D117), and whose tenant is the tenant of the connection; its precondition is a secret reference registered with the Secret Broker with the purposes its callers ask, tool-call for the change proposal, delivery for the certification and, for the template-feed project, the purpose that feature template-registry-service names for its read; it names the four calls, RegisterConnection with an Idempotency-Key, VerifyConnection with an Idempotency-Key, SetGrant for subject kind Project and, in the repository of ConnectorRegistryService, CertifyConnector, and the evidence that the connection is usable, ListConnections answering 200 with the connection in state Active and healthy with a grant count of at least one, and the ConnectionStateChanged and ConnectionGrantChanged records in the outbox; it states that SetGrant is allowed under the platform bundle for a Workspace admin of the project and the Platform admin (D129) and answered 403 for any other caller, and holds no token, credential, reference value or limit. ConnectSoft.AI.SoftwareFactory.IntegrationService
AIFACTORY-TASK-759 Verify integration-service-thin-contract by running the declared command verification Run dotnet build -c Release and dotnet test -c Release --no-build in the pipeline of the repository; a run that discovers no test counts as a failure; the runs pass and prove AC1 to AC4 of AIFACTORY-US-067, that is the scaffold with the Factory profile, exactly the five hosted operations of the thin scope and the 404 of RotateCredential and RevokeConnection, the messaging registration with three published events and no consumed event, the refusals before any handler, readiness that stays unready until integration-sql is migrated and the scan for secret values and tokens; the runbook of AIFACTORY-TASK-4070 is present in the repository documentation. ConnectSoft.AI.SoftwareFactory.IntegrationService

AIFACTORY-US-1004: Register an Azure DevOps connection with its credential kind and Key Vault reference, never its value, and announce it with ConnectionRegistered

behavior · persona workspace-admin As a workspace admin, I want to register the Azure DevOps connection of my organization with a reference to the secret that the vault holds, so that the Factory can reach the system of record without the secret ever passing through a Factory service.

A Workspace admin or Platform admin whose scope carries factory.connections.admin registers a connection through IntegrationService/RegisterConnection with an Idempotency-Key. The body names the connection name, the provider, the endpoint policy (allowed hosts, base URL, methods, rate limits, timeouts), the credential kind and the Key Vault reference of the credential. The value was written to Key Vault by the caller or the Secret Broker flow and is never posted here: the body has no member for a value, and a body that carries one, or any member the contract does not name, is refused with 400 and nothing is stored. The thin delivery registers connections of provider Azure DevOps only; another provider is refused with 400 until the complete delivery in I5. The connection belongs to the tenant of the token; the route names no project, and the project that may use the connection is named by its grant (AIFACTORY-US-1007). The service writes the Connection in state Draft and not healthy, with its rotation metadata, the rotation period of the provider policy or Integration:Connections:DefaultRotationDays where it sets none and the next rotation due, together with the ConnectionRegistered outbox record and the audit evidence event AuditEvidenceSubmitted on audit.evidence.v1.evidence-submitted in one transaction, and answers 201 with the location of the connection. A repeated call with the same key and the same body returns the same connection and changes nothing; the same key with a different body is refused with 409, and so is a second connection with the same name in the tenant. A token without the scope is answered 403. The reference is not resolved at registration: whether it resolves and works is proven by the verification, and until then the connection cannot be used. ConnectionRegistered carries connectionId, tenantId, provider and credentialKind and no reference and no value; StudioBff and AuditService handle it in their own PBIs. The credential reference is held in the row and, once the connection is resolved, in the broker ticket of Connections.Resolve (AIFACTORY-US-1008) only; it is in no list reply, event, audit evidence record, log record, activity or metric. The counter connectsoft.factory.integration.connections moves for the tenant, the provider and the state Draft.

Acceptance criteria

AC1 Given a caller with factory.connections.admin and a valid body for provider Azure DevOps with credential kind and Key Vault reference, when IntegrationService/RegisterConnection is called with an Idempotency-Key, then the response is 201 with the location, the IntegrationService/Connection is in state Draft and not healthy with its rotation metadata, and the IntegrationService/ConnectionRegistered outbox record and the audit evidence event are written in the same transaction (SCN-IntegrationService-001, ADR-0012).
AC2 Given the same call repeated with the same key and body, then the same connection is returned and nothing changes; given the same key with a different body or a second connection with the same name in the tenant, then 409; given a body with a member for a credential value, an unknown member or another provider than Azure DevOps, then 400 and nothing is stored; given a token without the scope, then 403; no refusal writes a row or an event (SCN-IntegrationService-001, ADR-0015).
AC3 Given the connection registered, when the outbox dispatcher of the integration profile publishes IntegrationService/ConnectionRegistered on connections.connections.v1.connection-registered, then the event is sent under the run event envelope with connectionId, tenantId, provider and credentialKind and without the reference, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-IntegrationService-008, ADR-0012).
AC4 Given the registration, when the row, the event, the audit evidence, the log records and the metrics are inspected, then the reference is held in the row and, for a resolved connection, in the broker ticket of the resolution that AIFACTORY-US-1008 delivers only, and in none of the event, the audit evidence, the log records, the activities or the metrics, no secret value exists anywhere, and connectsoft.factory.integration.connections counts the connection for the tenant, the provider and the state Draft (ADR-0019, model/services/integration/IntegrationService.yaml).
Traces: services IntegrationService
Traces: aggregates IntegrationService/Connection
Traces: apis IntegrationService/RegisterConnection
Traces: events IntegrationService/ConnectionRegistered
Traces: descriptors run-event-envelope-v1, audit-evidence-v1
Traces: adrs ADR-0012, ADR-0015, ADR-0019
Traces: requirements FR-01, NFR-02, NFR-05
Traces: scenarios SCN-IntegrationService-001, SCN-IntegrationService-008
Relates: screens connections
Depends on feature:component-base-template-factory-profile, feature:contracts-package, feature:component-audit-factory-evidence
Sources model/services/integration/IntegrationService.yaml, docs/planes/capability-tools/connectors/services/integration-service/index.md#domain-model, docs/planes/capability-tools/connectors/services/integration-service/ddl.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-4041 Migration and mappings of Connections and ConnectionGrants in integration-sql migration The tables Connections and ConnectionGrants of model/services/integration/IntegrationService.yaml exist with their columns, keys, the foreign key of a grant to its connection, the unique indexes UX_Connections_Tenant_Name and UX_Grants_Connection_Subject and the index IX_Connections_Provider_State; no column holds a secret value; the mappings carry the tenant row filter of the Factory profile; mapping tests run against an isolated test database, never a shared one. ConnectSoft.AI.SoftwareFactory.IntegrationService
AIFACTORY-TASK-4042 RegisterConnection with its Idempotency-Key, the Draft connection and ConnectionRegistered in one transaction implementation RegisterConnection validates the body, refuses a credential value member, an unknown member and a provider other than Azure DevOps with 400, writes the Connection in Draft and not healthy with its rotation metadata, the ConnectionRegistered outbox record and AuditEvidenceSubmitted in one transaction, answers 201, returns the same connection for a repeated key and body, answers 409 for a key with a different body and for a duplicate name and 403 without the scope, and moves connectsoft.factory.integration.connections. ConnectSoft.AI.SoftwareFactory.IntegrationService
AIFACTORY-TASK-4043 Verify the registration of a connection through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-IntegrationService-001\|Scenario=SCN-IntegrationService-008)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1004: the 201 with the Draft connection and the outbox record, the repeated key, the 409 for a different body and a duplicate name, the 400 for a value member, an unknown member and another provider, the 403, the publication of ConnectionRegistered under the run event envelope with retry, and the scan for secret values. ConnectSoft.AI.SoftwareFactory.IntegrationService

AIFACTORY-US-1005: List the connections of a tenant with provider, state, health, rotation due and grant counts and without any credential

behavior · persona workspace-admin As a workspace admin, I want to see the connections of my tenant with their state, health, rotation due and how many subjects hold a grant, so that I know whether the Azure DevOps connection my project uses is active and granted before a run needs it.

A caller whose scope carries factory.connections.read (Observer, Operator, Workspace admin or Platform admin) lists the connections through IntegrationService/ListConnections. The tenant comes from the validated token; the route names no project, because a connection belongs to its tenant and the projects that may use it are named by its grants. The response is 200 with the connections of that tenant only, each with connectionId, name, provider, credential kind, state, health, last verification, the next rotation due and the count of its grants. The list carries neither the credential reference nor any value: the reference is held in the row and in the broker ticket of Connections.Resolve only (D129), which the caller presents to the Secret Broker, and never in a list reply, an event, a log record, an activity or a metric. The tenant row filter of the Factory profile makes the connections of another tenant invisible; the list never confirms that one exists. A call without a token is answered 401 and a token without the scope 403; when integration-sql is unavailable the call fails fast with 503 and a problem response and no partial list. Nothing is written by the read and no event is published. The Studio screen of connections reads the same list through StudioBff in its own increment.

Acceptance criteria

AC1 Given a connection of the tenant of the caller in state Active with two grants, when a caller with factory.connections.read calls IntegrationService/ListConnections, then the response is 200 with the connection carrying connectionId, name, provider, credential kind, state, health, last verification, next rotation due and the grant count 2, without the credential reference and without any value, and nothing is written (SCN-IntegrationService-002).
AC2 Given fixture connections of tenant A and tenant B inserted directly into the isolated test database, when an Observer of tenant B calls IntegrationService/ListConnections, then only the connections of tenant B are returned and the connection of tenant A is not revealed (SCN-IntegrationService-002, ADR-0015).
AC3 Given a call without a token, a token without factory.connections.read or an unavailable integration-sql, when IntegrationService/ListConnections is called, then the answer is 401, 403 or 503 with a problem response, no partial list is returned and no state changes (SCN-IntegrationService-002).
Traces: services IntegrationService
Traces: aggregates IntegrationService/Connection
Traces: apis IntegrationService/ListConnections
Traces: adrs ADR-0015, ADR-0019
Traces: requirements FUX-01
Traces: scenarios SCN-IntegrationService-002
Relates: screens connections
Depends on AIFACTORY-US-1004
Sources model/services/integration/IntegrationService.yaml, docs/planes/capability-tools/connectors/services/integration-service/index.md#apis

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-4044 ListConnections read model with the tenant row filter and grant counts implementation ListConnections returns the connections of the trusted tenant with connectionId, name, provider, credential kind, state, health, last verification, next rotation due and grant count, never the credential reference, answers 401 and 403 through the policies of the Factory profile and 503 with a problem response when the store is unavailable, and writes nothing. ConnectSoft.AI.SoftwareFactory.IntegrationService
AIFACTORY-TASK-4045 Verify the list of connections through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-IntegrationService-002"; a zero-match filter counts as a failure; the tests prove AC1 to AC3 of AIFACTORY-US-1005: the list with its members and the grant count and without the reference, the two-tenant fixture rows, the 401, the 403 and the 503 of an unavailable store. ConnectSoft.AI.SoftwareFactory.IntegrationService

AIFACTORY-US-1006: Verify a connection through the Secret Broker, activate it on success, mark it Degraded on failure and announce each state change

behavior · persona workspace-admin As a workspace admin, I want to verify that the credential of a connection resolves and works and to have the connection activated only then, so that no service uses a connection whose credential was never proven, and a credential that stopped working is visible as Degraded.

A caller whose scope carries factory.connections.admin verifies a connection through IntegrationService/VerifyConnection with an Idempotency-Key; the path names the connection. The verification is a read-only probe of class external: the service asks SecretBrokerService/SecretBroker.Verify whether the credential reference resolves and the credential works at the provider, and the broker answers without issuing the credential, so IntegrationService never holds it. The service decides no approval. The answer is 200 with the outcome, verified or not verified with the reason the broker gives, and the state of the connection. Integration:Connections:VerifyOnActivate makes a successful verification the precondition of Active, and the model names no other operation for the trigger Activate, so a successful verification of a Draft connection moves it from Draft to Verified (VerificationSucceeded) and from Verified to Active (Activate) in one transaction, sets it healthy and records the verification time; each transition writes its own ConnectionStateChanged outbox record with fromState and toState, and the audit evidence event AuditEvidenceSubmitted is written in the same transaction. Every verification that reaches an outcome is an external probe and is recorded: the audit evidence event AuditEvidenceSubmitted with the outcome and the reason the broker gives is written to the outbox for it, also when no state changes. A failed verification of a Draft connection changes no state and writes no ConnectionStateChanged, and its audit evidence records the outcome not verified with the reason. A failed verification of an Active connection moves it to Degraded and not healthy, and a successful verification of a Degraded connection moves it back to Active, each with its ConnectionStateChanged, as the failure mode of an expired credential at the provider states; a successful verification of an Active connection records the time and writes no ConnectionStateChanged, only its audit evidence. A repeated call with the same key returns the same outcome and changes nothing. A token without the scope is answered 403; a connection that does not exist in the tenant of the caller, or that belongs to another tenant, is answered 404, the same answer in both cases (ADR-0015 amendment D113). SecretBrokerService is required and fail-fast: when it does not answer, the call fails with 503, the state stays as it was and nothing is published, because no connection is activated without a verification (fail closed). ConnectionStateChanged carries connectionId, tenantId, fromState and toState; its consumers, ConnectorRegistryService, ToolAdapterService, KnowledgeIngestionService, McpServerRegistryService, StudioBff and AuditService, handle it in their own PBIs. The periodic probe of ConnectionHealthProbe, suspension and revocation arrive with the complete delivery in I5. connectsoft.factory.integration.connections moves with every state change.

Acceptance criteria

AC1 Given a Draft IntegrationService/Connection of the tenant of the caller and SecretBrokerService/SecretBroker.Verify answering that the reference resolves and the credential works, when IntegrationService/VerifyConnection is called with an Idempotency-Key, then the response is 200 with the outcome verified, the connection is Active and healthy with its verification time, and two IntegrationService/ConnectionStateChanged outbox records, Draft to Verified and Verified to Active, and the audit evidence event are written in the same transaction (SCN-IntegrationService-003, SCN-IntegrationService-009).
AC2 Given the broker answering not verified, when a Draft connection is verified, then the response is 200 with the outcome and the reason, no state changes, no IntegrationService/ConnectionStateChanged is written and the audit evidence event with the outcome not verified and the reason is written; when an Active connection is verified, then it becomes Degraded and not healthy with its IntegrationService/ConnectionStateChanged and its audit evidence; given a Degraded connection verified successfully, then it is Active again with its event and its audit evidence; given an Active connection verified successfully, then only the verification time changes, no IntegrationService/ConnectionStateChanged is written and the audit evidence records the outcome (SCN-IntegrationService-003).
AC3 Given the same call repeated with the same key, then the same outcome returns and nothing changes; given a token without the scope, a connection of another tenant or an unknown connection, or a broker that does not answer, then the answer is 403, 404 (the same for a foreign and an unknown connection, ADR-0015 amendment D113) or 503 with a problem response, the state stays as it was and nothing is published (SCN-IntegrationService-003, ADR-0015).
AC4 Given a state change committed, when the outbox dispatcher publishes IntegrationService/ConnectionStateChanged on connections.connections.v1.connection-state-changed, then the event is sent under the run event envelope with connectionId, tenantId, fromState and toState, the two events of an activation in commit order, and a transport outage is retried with backoff so no event is lost or duplicated under its event id (SCN-IntegrationService-009, ADR-0012).
AC5 Given the calls recorded by the fake of SecretBrokerService/SecretBroker.Verify and the captured logs and activities of a verification, when they are inspected, then the service sent the reference and received no credential, and no secret value appears anywhere (ADR-0019, NFR-02).
Traces: services IntegrationService, SecretBrokerService
Traces: aggregates IntegrationService/Connection
Traces: apis IntegrationService/VerifyConnection, SecretBrokerService/SecretBroker.Verify
Traces: events IntegrationService/ConnectionStateChanged
Traces: descriptors run-event-envelope-v1
Traces: adrs ADR-0012, ADR-0015, ADR-0019
Traces: requirements NFR-02, NFR-05
Traces: scenarios SCN-IntegrationService-003, SCN-IntegrationService-009
Relates: screens connections
Depends on AIFACTORY-US-1004, feature:secret-broker-service
Sources model/services/integration/IntegrationService.yaml, model/services/governance/SecretBrokerService.yaml, docs/planes/capability-tools/connectors/services/integration-service/index.md#failure-and-recovery

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-4046 VerifyConnection through SecretBroker.Verify with the transitions to Active and Degraded and their events implementation VerifyConnection calls SecretBroker.Verify through a typed gRPC client with the reference and receives no credential, answers 200 with the outcome and the state, commits Draft to Verified to Active, Active to Degraded or Degraded to Active with one ConnectionStateChanged outbox record per transition and AuditEvidenceSubmitted in the transaction, writes AuditEvidenceSubmitted with the outcome and the reason also for a verification that changes no state, a failed verification of a Draft connection and a successful verification of an Active connection, records the verification time, returns the same outcome for a repeated key, answers 403, 404 for a foreign and an unknown connection alike and 503 without a state change when the broker does not answer, and moves connectsoft.factory.integration.connections. ConnectSoft.AI.SoftwareFactory.IntegrationService
AIFACTORY-TASK-4047 Fake of SecretBroker.Verify for the acceptance suite fixture The acceptance suite holds a fake of SecretBrokerService/SecretBroker.Verify that records the reference it received, answers verified or not verified with a reason, and can be stopped, so every transition and the fail-closed answer are proven without a vault or a provider. ConnectSoft.AI.SoftwareFactory.IntegrationService
AIFACTORY-TASK-4048 Verify the verification and the state changes through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-IntegrationService-003\|Scenario=SCN-IntegrationService-009)"; a zero-match filter counts as a failure; the tests prove AC1 to AC5 of AIFACTORY-US-1006: the activation with two events, the failed verification of a Draft connection with its audit evidence and no ConnectionStateChanged, the failed verification of an Active connection, the recovery from Degraded, the successful verification of an Active connection with its audit evidence and no ConnectionStateChanged, the repeated key, the 403, the 404 for a foreign and an unknown connection, the 503 with the broker stopped, the publication of ConnectionStateChanged in commit order and the recorded broker calls without a credential. ConnectSoft.AI.SoftwareFactory.IntegrationService

AIFACTORY-US-1007: Grant or narrow the use of a connection by a project after the project scope and the grant policy allow it, announced by ConnectionGrantChanged

behavior · persona workspace-admin As a workspace admin, I want to grant the Azure DevOps connection to my project and narrow what the project may do with it, so that only the project I name can resolve the connection and only within the hosts and methods I allow.

A caller whose scope carries factory.connections.admin sets a grant through IntegrationService/SetGrant, PUT /factory/connections/{connectionId}/grants/{subjectKind}/{subjectId}, with a body that holds the scopes narrowing the endpoint policy for the subject and an optional expiry. The thin delivery grants to subject kind Project, which is what one Azure DevOps connection per project needs; the kinds Agent, Tool, Source and McpServer are refused with 400 until the complete delivery in I5. For a Project grant the path names the project in subjectId, so the route names its project in the path and never in a header. The service asks ProjectService/Projects.ResolveScope for the project and the roles of the caller in it, and PolicyEngineService/Policy.Decide for the grant policy, who may grant what to whom. The request is a policy-decision-request-v1 with the action kind connection-grant, which pairs with the domain ConnectionGrant so that the caller names no domain, the target connection-grant, the side-effect class shared-write, the granting subject with its roles in the project, and the subject kind and subject of the grant; the kind is fixed in the service and no setting names it (D127, D129). The policy decision alone decides and the service decides no approval: only the outcome allow writes the grant, any other outcome is answered 403 with the outcome and the reason of the decision, and an answer that is no decision is answered 403 with the reason no-decision, so no grant exists without an allowing decision (fail closed). The platform bundle allows the action kind connection-grant for a subject who is Workspace admin of the project or the Platform admin (AIFACTORY-US-917 of feature policy-engine-service, D129), and Policy.Decide answers deny for an action no rule matches, so on a deployed I1 instance a grant of those callers is written and a grant of any other caller is answered 403 with the reason of the deny. The grant is written or replaced on the unique key of connection, subject kind and subject, with the subject who granted it and the time; a first grant writes ConnectionGrantChanged with the change set, a grant with fewer scopes than before with the change narrowed, a grant with other scopes with the change set, each in the transaction with the audit evidence event AuditEvidenceSubmitted; the same body repeated is answered 200 and writes nothing and no event, because the operation is naturally idempotent. A grant may be set on a connection in any state; it is used only once the connection is Active (AIFACTORY-US-1008). A token without the scope is answered 403; a connection of another tenant or an unknown connection, and a project that does not exist in the tenant, are answered 404 (ADR-0015 amendment D113). ProjectService and PolicyEngineService are required and fail-fast: when one does not answer, the call fails with 503 and nothing changes. The model has no operation that removes a grant; removal and the revocation of project grants when a project is closing (XL-13) arrive with the complete delivery. ConnectionGrantChanged carries connectionId, tenantId, subjectKind, subjectId and change; StudioBff and AuditService handle it in their own PBIs.

Acceptance criteria

AC1 Given an IntegrationService/Connection of the tenant of the caller, a project of that tenant, the fake of ProjectService/Projects.ResolveScope and the fake of PolicyEngineService/Policy.Decide answering allow, as the platform bundle does for a Workspace admin of the project (D129), when IntegrationService/SetGrant is called for subject kind Project with scopes, then the response is 200, the grant is written with the granting subject and the time, and the IntegrationService/ConnectionGrantChanged outbox record with the change set and the audit evidence event are written in the same transaction (SCN-IntegrationService-004, SCN-IntegrationService-010).
AC2 Given the same body repeated, then the response is 200 and nothing is written and no event is published; given a body with fewer scopes, then the grant is narrowed and IntegrationService/ConnectionGrantChanged carries the change narrowed; given an expiry, then it is stored with the grant (SCN-IntegrationService-004).
AC3 Given a token without the scope, a policy decision other than allow, among them the deny that PolicyEngineService/Policy.Decide answers under the platform bundle for a caller who is neither Workspace admin of the project nor Platform admin, an answer that is no decision, a connection of another tenant or an unknown connection, a project that does not exist in the tenant, a subject kind other than Project, or ProjectService or PolicyEngineService that does not answer, when IntegrationService/SetGrant is called, then the answer is 403, 403 with the outcome and the reason of the decision, 403 with the reason no-decision, 404, 404, 400 or 503 with a problem response, and no grant and no event are written (SCN-IntegrationService-004, ADR-0015).
AC4 Given a grant committed, when the outbox dispatcher publishes IntegrationService/ConnectionGrantChanged on connections.grants.v1.connection-grant-changed, then the event is sent under the run event envelope with connectionId, tenantId, subjectKind, subjectId and change, and a transport outage is retried with backoff so the event is neither lost nor duplicated under its event id (SCN-IntegrationService-010, ADR-0012).
Traces: services IntegrationService, ProjectService, PolicyEngineService
Traces: aggregates IntegrationService/Connection
Traces: apis IntegrationService/SetGrant, ProjectService/Projects.ResolveScope, PolicyEngineService/Policy.Decide
Traces: events IntegrationService/ConnectionGrantChanged
Traces: descriptors run-event-envelope-v1, policy-decision-request-v1
Traces: adrs ADR-0012, ADR-0015
Traces: requirements FR-01, FUX-01
Traces: scenarios SCN-IntegrationService-004, SCN-IntegrationService-010
Relates: screens connections
Depends on AIFACTORY-US-1004, feature:project-service, feature:policy-engine-service
Sources model/services/integration/IntegrationService.yaml, model/services/control-plane/ProjectService.yaml, model/services/governance/PolicyEngineService.yaml, docs/planes/capability-tools/connectors/services/integration-service/index.md#entities-and-value-objects

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-4049 SetGrant for subject kind Project after Projects.ResolveScope and Policy.Decide, with ConnectionGrantChanged implementation SetGrant accepts subject kind Project and refuses the other kinds with 400, resolves the project and the roles of the caller through Projects.ResolveScope, asks Policy.Decide for the grant policy with a policy-decision-request-v1 of the action kind connection-grant, fixed in the service, the target connection-grant and the class shared-write, writes the grant for the outcome allow only, answers 403 with the outcome and reason of any other decision and 403 with no-decision for an answer that is no decision, writes or replaces the grant on its unique key with grantedBy and grantedAt, writes ConnectionGrantChanged with the change set or narrowed and AuditEvidenceSubmitted in the transaction, answers 200 without a write for an identical body, 404 for a foreign or unknown connection and an unknown project, and 503 without a change when a dependency does not answer. ConnectSoft.AI.SoftwareFactory.IntegrationService
AIFACTORY-TASK-4050 Fakes of Projects.ResolveScope and Policy.Decide for the acceptance suite fixture The acceptance suite holds a fake of ProjectService/Projects.ResolveScope that answers a known project with the roles of the caller and an unknown project, and a fake of PolicyEngineService/Policy.Decide that answers allow, allow-with-approval and deny with a reason, the deny the platform bundle answers for a caller who is neither Workspace admin of the project nor Platform admin, and an answer that is no decision; it records the action kind connection-grant of each request; both record their calls and can be stopped. ConnectSoft.AI.SoftwareFactory.IntegrationService
AIFACTORY-TASK-4051 Verify the grant of a connection through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&(Scenario=SCN-IntegrationService-004\|Scenario=SCN-IntegrationService-010)"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1007: the first grant with the change set, the identical repeat without an event, the narrowing, the expiry, the 403 without the scope, on a denial, on the deny of the platform bundle for a caller without the role, on allow-with-approval and with no-decision, the action kind connection-grant on every decision request, the 404 for a foreign connection and an unknown project, the 400 for another subject kind, the 503 with each fake stopped and the publication of ConnectionGrantChanged with retry. ConnectSoft.AI.SoftwareFactory.IntegrationService

AIFACTORY-US-1008: Resolve the Azure DevOps connection of a project with its grant check and return the endpoint policy and a broker ticket, never a credential

behavior · persona operator As an operator, I want every service that calls Azure DevOps for a project to obtain the connection only through a grant check, so that a project without a grant, an inactive connection or a degraded credential stops the call before anything leaves the Factory.

ToolAdapterService resolves the connection of the project when propose-change-set opens the change proposal, which the tool opens itself through the connection and records through Pipelines.RecordProposal of PipelineExecutionService (D135), and ConnectorRegistryService resolves it when a capability of its connector is resolved and when it certifies the connector. Every resolution names a project: a discovery pass of TemplateRegistryService reaches this method through ConnectorRegistryService under the platform tenant and the template-feed project of the platform tenant, a project the installation supplies whose Project grant holds the Azure DevOps connection of the template sources, and a certification under the sandbox project of the platform tenant; no path of the chain resolves without a project. The caller presents a workload token with the service scope that names IntegrationService and forwards the tenant and the project of its scope in the gRPC metadata; the token carries no tenant claim, so the service reads the forwarded tenant and project only under that scope (ADR-0015 amendment D114). The request of IntegrationService/Connections.Resolve is execution-scope-v1, whose project is the subject of the grant check; an execution scope whose tenant differs from the forwarded tenant is refused with PERMISSION_DENIED and the reason scope-mismatch and selects no row. The service looks up the connection of provider Azure DevOps that holds an unexpired grant of subject kind Project for that project under the tenant row filter. It answers with the connection, its provider and credential kind, the endpoint policy narrowed by the scopes of the grant, and a broker ticket that names the connection, the credential reference and the subject; the ticket is the one place outside the row where the reference appears, it is never logged, measured or published, and the caller exchanges the ticket with SecretBrokerService/SecretBroker.Issue for a short-lived credential, and the broker decides that issuance under its own policy decision. The reply never carries a credential. The method is of class read and writes nothing; connectsoft.factory.integration.resolves counts every call by tenant, provider and outcome. A project without a grant, or with an expired grant, is answered PERMISSION_DENIED with the reason no-grant, so the action of the caller is denied with that reason and a Workspace admin grants (failure mode of a missing grant). A connection in Draft or Verified is answered FAILED_PRECONDITION with the reason not-active and a Degraded connection with the reason degraded, so dependent calls fail fast. A tenant with no Azure DevOps connection, and a connection of another tenant, are answered NOT_FOUND. The thin scope holds one Azure DevOps connection per project; when two connections of the provider grant the same project, the answer is FAILED_PRECONDITION with the reason ambiguous and nothing is chosen. A call without a workload identity, or a workload call that forwards no tenant, is refused with UNAUTHENTICATED by the Factory profile, a token without the service scope with PERMISSION_DENIED and a request without a project with INVALID_ARGUMENT; an unavailable integration-sql is answered UNAVAILABLE without a partial reply. When the Secret Broker is unavailable, the caller cannot exchange its ticket and makes no outbound call (fail closed). The model names execution-scope-v1 also as the reply, which has no member for the endpoint policy or the ticket; that is an open point for the owner, and the reply message is a provisional golden file until the owner names the descriptor.

Acceptance criteria

AC1 Given an Active and healthy Azure DevOps IntegrationService/Connection with an unexpired Project grant for project P, when IntegrationService/Connections.Resolve is called under a workload token with the service scope that forwards tenant A and project P, then the reply names the connection, provider, credential kind, the endpoint policy narrowed by the grant and a broker ticket for SecretBrokerService/SecretBroker.Issue, carries no credential, nothing is written and the resolve counter records the outcome granted (SCN-IntegrationService-007, NFR-02).
AC2 Given a project without a grant or with an expired grant, a connection in Draft, a Degraded connection, two Azure DevOps connections that grant the same project, a tenant without such a connection or a connection of another tenant, when IntegrationService/Connections.Resolve is called, then the answer is PERMISSION_DENIED with the reason no-grant, FAILED_PRECONDITION with not-active, degraded or ambiguous, or NOT_FOUND, nothing is written and the counter records the outcome (SCN-IntegrationService-007, ADR-0015).
AC3 Given a call without a workload identity, a workload call that forwards no tenant, a token without the service scope, an execution scope of another tenant than the forwarded one, a request without a project or an unavailable integration-sql, when the method is called, then it is refused with UNAUTHENTICATED, UNAUTHENTICATED, PERMISSION_DENIED, PERMISSION_DENIED with the reason scope-mismatch, INVALID_ARGUMENT or UNAVAILABLE respectively, no partial reply is returned and no state changes (SCN-IntegrationService-007, ADR-0015).
AC4 Given the proto of the method, when the contract test runs, then the provisional golden file of the reply holds the connection, the endpoint policy and the ticket and no member for a credential, and the test marks it provisional because execution-scope-v1 has no member for them (docs/reference/schemas/execution-scope.schema.json, ADR-0019).
Traces: services IntegrationService, SecretBrokerService
Traces: aggregates IntegrationService/Connection
Traces: apis IntegrationService/Connections.Resolve, SecretBrokerService/SecretBroker.Issue
Traces: descriptors execution-scope-v1
Traces: adrs ADR-0015, ADR-0019, ADR-0022
Traces: requirements FR-05, NFR-02, XL-10
Traces: scenarios SCN-IntegrationService-007
Depends on AIFACTORY-US-1006, AIFACTORY-US-1007, feature:secret-broker-service
Sources model/services/integration/IntegrationService.yaml, docs/reference/schemas/execution-scope.schema.json, docs/planes/capability-tools/connectors/services/integration-service/index.md#security

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-4052 Provisional reply message of Connections.Resolve contract The proto keeps execution-scope-v1 as the request, with no connection member, and fixes the reply message (connectionId, provider, credentialKind, the narrowed endpoint policy and the broker ticket with connectionId, credential reference and subject, no credential member) as a provisional golden file; the ticket is the only member outside the row that holds the credential reference, and a test fails when the reference reaches a log record, an activity, a metric or an event; the file is marked provisional in the contract test until the owner names the reply descriptor, because docs/reference/schemas/execution-scope.schema.json has no member for it. ConnectSoft.AI.SoftwareFactory.IntegrationService
AIFACTORY-TASK-4053 Connections.Resolve with the grant check, the state check and the outcome counter implementation Connections.Resolve reads the forwarded tenant and project only under the service scope, refuses a differing execution scope with PERMISSION_DENIED and scope-mismatch, finds the Azure DevOps connection with an unexpired Project grant for the project, returns the reply with the narrowed endpoint policy and the broker ticket and no credential, answers PERMISSION_DENIED no-grant, FAILED_PRECONDITION not-active, degraded or ambiguous, NOT_FOUND, INVALID_ARGUMENT and UNAVAILABLE as AIFACTORY-US-1008 states, writes nothing and records connectsoft.factory.integration.resolves by tenant, provider and outcome. ConnectSoft.AI.SoftwareFactory.IntegrationService
AIFACTORY-TASK-4054 Verify the resolution of a connection through the acceptance suite verification Run dotnet test -c Release --filter "Category=Acceptance&Scenario=SCN-IntegrationService-007"; a zero-match filter counts as a failure; the tests prove AC1 to AC4 of AIFACTORY-US-1008 with connections and grants of two tenants written through the operations of this feature: the granted reply with the ticket, no-grant, the expired grant, not-active, degraded, ambiguous, NOT_FOUND for a foreign tenant, the six refusals, the outcome counter and the provisional golden file. ConnectSoft.AI.SoftwareFactory.IntegrationService