ahmido
1debe40ced
## Summary - implement the provider capability registry and derived capability evaluation flow - update provider connections, onboarding, required-permissions diagnostics, and provider blocker translation to use capability-first summaries - add bounded unit, feature, and browser test coverage plus the prepared Spec 283 artifacts ## Notes - branch: `283-provider-capability-registry` - commit: `74e75c3e` - no additional validation commands were run in this git/PR flow step Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #342
394 lines
11 KiB
YAML
394 lines
11 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Provider Capability Registry Logical Contract
|
|
version: 0.1.0
|
|
description: >-
|
|
Logical contract for the derived provider capability registry and its
|
|
consumer surfaces. This models shared capability truth only; it does not
|
|
declare new persisted resources or public API commitments.
|
|
x-logical-contract: true
|
|
x-initial-capability-inventory:
|
|
provider_connection_check:
|
|
label: Provider connection check
|
|
operationTypes:
|
|
- provider.connection.check
|
|
providerRequirementKeys:
|
|
- permissions.admin_consent
|
|
inventory_read:
|
|
label: Inventory read
|
|
operationTypes:
|
|
- inventory.sync
|
|
providerRequirementKeys:
|
|
- permissions.intune_configuration
|
|
- permissions.intune_apps
|
|
configuration_read:
|
|
label: Configuration read
|
|
operationTypes:
|
|
- compliance.snapshot
|
|
providerRequirementKeys:
|
|
- permissions.intune_configuration
|
|
restore_execute:
|
|
label: Restore execute
|
|
operationTypes:
|
|
- restore.execute
|
|
providerRequirementKeys:
|
|
- permissions.intune_configuration
|
|
- permissions.intune_rbac_assignments
|
|
directory_groups_read:
|
|
label: Directory groups read
|
|
operationTypes:
|
|
- directory.groups.sync
|
|
providerRequirementKeys:
|
|
- permissions.directory_groups
|
|
directory_role_definitions_read:
|
|
label: Directory role definitions read
|
|
operationTypes:
|
|
- directory.role_definitions.sync
|
|
providerRequirementKeys:
|
|
- provider.directory_role_definitions
|
|
- permissions.admin_consent
|
|
paths:
|
|
/logical/provider-connections/{providerConnectionId}/capabilities:
|
|
get:
|
|
summary: Resolve capability summary for one provider connection
|
|
operationId: getProviderConnectionCapabilities
|
|
parameters:
|
|
- name: providerConnectionId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Capability summary for provider-connections and related context
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProviderConnectionCapabilitySummary'
|
|
/logical/managed-environments/{managedEnvironmentId}/required-permission-capabilities:
|
|
get:
|
|
summary: Resolve capability-grouped required-permissions diagnostics
|
|
operationId: getRequiredPermissionCapabilityGroups
|
|
parameters:
|
|
- name: managedEnvironmentId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Capability groups with nested permission evidence
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- groups
|
|
properties:
|
|
groups:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/RequiredPermissionsCapabilityGroup'
|
|
/logical/managed-environments/{managedEnvironmentId}/onboarding-provider-capability-assist:
|
|
get:
|
|
summary: Resolve onboarding capability assist for the current managed environment
|
|
operationId: getOnboardingProviderCapabilityAssist
|
|
parameters:
|
|
- name: managedEnvironmentId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
- name: providerConnectionId
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Capability-first onboarding assist payload
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/OnboardingCapabilityAssist'
|
|
/logical/provider-operations/{operationType}/capability-gate:
|
|
post:
|
|
summary: Evaluate provider capability requirements before provider-operation start
|
|
operationId: evaluateProviderOperationCapabilityGate
|
|
parameters:
|
|
- name: operationType
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- managedEnvironmentId
|
|
properties:
|
|
managedEnvironmentId:
|
|
type: integer
|
|
providerConnectionId:
|
|
type: integer
|
|
nullable: true
|
|
responses:
|
|
'200':
|
|
description: Capability gate result for operation start
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/OperationCapabilityGateResult'
|
|
/logical/provider-capability-explanations:
|
|
post:
|
|
summary: Translate a provider blocker into a capability-first explanation
|
|
operationId: getProviderCapabilityExplanation
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- providerCapabilityKey
|
|
properties:
|
|
providerCapabilityKey:
|
|
$ref: '#/components/schemas/ProviderCapabilityKey'
|
|
reasonCode:
|
|
type: string
|
|
nullable: true
|
|
managedEnvironmentId:
|
|
type: integer
|
|
nullable: true
|
|
providerConnectionId:
|
|
type: integer
|
|
nullable: true
|
|
responses:
|
|
'200':
|
|
description: Capability-first support or contextual-help explanation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ProviderCapabilityExplanation'
|
|
components:
|
|
schemas:
|
|
ProviderCapabilityKey:
|
|
type: string
|
|
enum:
|
|
- provider_connection_check
|
|
- inventory_read
|
|
- configuration_read
|
|
- restore_execute
|
|
- directory_groups_read
|
|
- directory_role_definitions_read
|
|
ProviderCapabilityStatus:
|
|
type: string
|
|
enum:
|
|
- supported
|
|
- missing
|
|
- blocked
|
|
- unknown
|
|
- not_applicable
|
|
ProviderCapabilityDefinition:
|
|
type: object
|
|
required:
|
|
- key
|
|
- label
|
|
- operationTypes
|
|
- providerRequirementKeys
|
|
properties:
|
|
key:
|
|
$ref: '#/components/schemas/ProviderCapabilityKey'
|
|
label:
|
|
type: string
|
|
operationTypes:
|
|
type: array
|
|
items:
|
|
type: string
|
|
providerRequirementKeys:
|
|
type: array
|
|
items:
|
|
type: string
|
|
primaryReasonCodes:
|
|
type: array
|
|
items:
|
|
type: string
|
|
remediationRouteKind:
|
|
type: string
|
|
ProviderCapabilityResult:
|
|
type: object
|
|
required:
|
|
- providerCapabilityKey
|
|
- status
|
|
- providerRequirementKeys
|
|
- primaryMessage
|
|
properties:
|
|
providerCapabilityKey:
|
|
$ref: '#/components/schemas/ProviderCapabilityKey'
|
|
status:
|
|
$ref: '#/components/schemas/ProviderCapabilityStatus'
|
|
reasonCode:
|
|
type: string
|
|
nullable: true
|
|
providerRequirementKeys:
|
|
type: array
|
|
items:
|
|
type: string
|
|
lastCheckedAt:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
primaryMessage:
|
|
type: string
|
|
providerHint:
|
|
type: string
|
|
nullable: true
|
|
evidenceCounts:
|
|
type: object
|
|
additionalProperties:
|
|
type: integer
|
|
PermissionEvidenceRow:
|
|
type: object
|
|
required:
|
|
- key
|
|
- type
|
|
- status
|
|
properties:
|
|
key:
|
|
type: string
|
|
type:
|
|
type: string
|
|
enum:
|
|
- application
|
|
- delegated
|
|
status:
|
|
type: string
|
|
enum:
|
|
- granted
|
|
- missing
|
|
- error
|
|
description:
|
|
type: string
|
|
nullable: true
|
|
features:
|
|
type: array
|
|
items:
|
|
type: string
|
|
RequiredPermissionsCapabilityGroup:
|
|
type: object
|
|
required:
|
|
- providerCapabilityKey
|
|
- label
|
|
- status
|
|
- summary
|
|
- rows
|
|
properties:
|
|
providerCapabilityKey:
|
|
$ref: '#/components/schemas/ProviderCapabilityKey'
|
|
label:
|
|
type: string
|
|
status:
|
|
$ref: '#/components/schemas/ProviderCapabilityStatus'
|
|
summary:
|
|
type: string
|
|
missingRequirementKeys:
|
|
type: array
|
|
items:
|
|
type: string
|
|
rows:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/PermissionEvidenceRow'
|
|
ProviderConnectionCapabilitySummary:
|
|
type: object
|
|
required:
|
|
- providerConnectionId
|
|
- primaryCapabilityKey
|
|
- primaryCapabilitySelectionRule
|
|
- capabilities
|
|
- nextStep
|
|
properties:
|
|
providerConnectionId:
|
|
type: integer
|
|
primaryCapabilityKey:
|
|
$ref: '#/components/schemas/ProviderCapabilityKey'
|
|
primaryCapabilitySelectionRule:
|
|
type: string
|
|
enum:
|
|
- highest_risk_then_surface_relevance
|
|
capabilities:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ProviderCapabilityResult'
|
|
nextStep:
|
|
type: string
|
|
nullable: true
|
|
OnboardingCapabilityAssist:
|
|
type: object
|
|
required:
|
|
- managedEnvironmentId
|
|
- capabilities
|
|
properties:
|
|
managedEnvironmentId:
|
|
type: integer
|
|
providerConnectionId:
|
|
type: integer
|
|
nullable: true
|
|
primaryCapabilityKey:
|
|
$ref: '#/components/schemas/ProviderCapabilityKey'
|
|
capabilities:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ProviderCapabilityResult'
|
|
nextStep:
|
|
type: string
|
|
nullable: true
|
|
OperationCapabilityGateResult:
|
|
type: object
|
|
required:
|
|
- operationType
|
|
- requiredProviderCapabilityKeys
|
|
- capabilities
|
|
- decision
|
|
properties:
|
|
operationType:
|
|
type: string
|
|
requiredProviderCapabilityKeys:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ProviderCapabilityKey'
|
|
capabilities:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ProviderCapabilityResult'
|
|
decision:
|
|
type: string
|
|
enum:
|
|
- allow
|
|
- block
|
|
- unknown
|
|
nextStep:
|
|
type: string
|
|
nullable: true
|
|
ProviderCapabilityExplanation:
|
|
type: object
|
|
required:
|
|
- providerCapabilityKey
|
|
- primaryMessage
|
|
properties:
|
|
providerCapabilityKey:
|
|
$ref: '#/components/schemas/ProviderCapabilityKey'
|
|
reasonCode:
|
|
type: string
|
|
nullable: true
|
|
primaryMessage:
|
|
type: string
|
|
providerHint:
|
|
type: string
|
|
nullable: true
|
|
requiredPermissionsUrl:
|
|
type: string
|
|
nullable: true |