427 lines
13 KiB
YAML
427 lines
13 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: TenantPilot Governance-as-a-Service Packaging v1 (Conceptual)
|
|
version: 0.1.0
|
|
description: |
|
|
Conceptual contract for the Governance-as-a-Service Packaging v1 planning package.
|
|
|
|
These paths describe existing Filament admin and tenant-scoped routes reused by
|
|
the implementation. The schemas document the derived package summary and
|
|
package-availability contract expected over existing review, review-pack,
|
|
evidence, stored-report-backed evidence, and governance-decision truth; they
|
|
do not define a new public REST API.
|
|
servers:
|
|
- url: /
|
|
paths:
|
|
/admin/reviews/workspace:
|
|
get:
|
|
summary: View management-ready package readiness in the customer review workspace
|
|
description: |
|
|
Existing admin-plane workspace page reused as the primary decision surface.
|
|
The route remains read-only, tenant-safe, and package-readiness remains
|
|
informational rather than a second competing action path.
|
|
parameters:
|
|
- in: query
|
|
name: tenant
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: |
|
|
Optional tenant prefilter using the current tenant id or external id
|
|
pattern already accepted by the workspace page.
|
|
responses:
|
|
'200':
|
|
description: Workspace page rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CustomerReviewWorkspacePageModel'
|
|
'404':
|
|
description: Not found for non-members, actors without entitled tenants, or explicit out-of-scope tenant targeting
|
|
|
|
/admin/t/{tenant}/reviews/{review}:
|
|
get:
|
|
summary: Open the management-ready package context for a released review
|
|
description: |
|
|
Existing tenant-scoped released-review detail route reused as the secondary
|
|
package context surface. The customer-workspace flow uses the existing
|
|
`customer_workspace=1` query flag to keep the detail read-only and
|
|
management-ready.
|
|
parameters:
|
|
- in: path
|
|
name: tenant
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
- in: path
|
|
name: review
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
- in: query
|
|
name: customer_workspace
|
|
required: false
|
|
schema:
|
|
type: boolean
|
|
description: Existing query-context flag that suppresses operator lifecycle actions on the detail surface.
|
|
responses:
|
|
'200':
|
|
description: Released-review detail rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GovernancePackageDetailModel'
|
|
'403':
|
|
description: Forbidden for an in-scope actor missing the inherited review-view capability on the reused route
|
|
'404':
|
|
description: Not found for non-members, tenant mismatches, or out-of-scope review targets
|
|
|
|
/admin/review-packs/{reviewPack}/download:
|
|
get:
|
|
summary: Download the current review-pack-backed governance package artifact
|
|
description: |
|
|
Existing signed review-pack download route reused as the default package
|
|
delivery seam. The management-ready path should reuse this route rather than
|
|
creating a new package artifact namespace or triggering generation.
|
|
parameters:
|
|
- in: path
|
|
name: reviewPack
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
- in: query
|
|
name: source_surface
|
|
required: false
|
|
schema:
|
|
type: string
|
|
- in: query
|
|
name: review_id
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
- in: query
|
|
name: tenant_filter_id
|
|
required: false
|
|
schema:
|
|
type: integer
|
|
- in: query
|
|
name: interpretation_version
|
|
required: false
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'302':
|
|
description: Signed download redirect to the current review-pack artifact
|
|
'403':
|
|
description: Forbidden for an in-scope actor missing the review-pack capability or a valid signature
|
|
'404':
|
|
description: Not found for non-members, tenant mismatches, or inaccessible review packs
|
|
|
|
/admin/t/{tenant}/evidence/{evidenceSnapshot}:
|
|
get:
|
|
summary: Open supporting evidence from the management-ready package context
|
|
description: |
|
|
Existing tenant-scoped evidence detail route reused only after explicit
|
|
drilldown from the released-review detail surface and current capability
|
|
checks.
|
|
parameters:
|
|
- in: path
|
|
name: tenant
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
- in: path
|
|
name: evidenceSnapshot
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
- in: query
|
|
name: source_surface
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: Existing source-surface metadata hook reused by the shared audit path.
|
|
responses:
|
|
'200':
|
|
description: Evidence proof detail rendered
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Forbidden for an in-scope actor missing the evidence capability
|
|
'404':
|
|
description: Not found for non-members, mismatched tenant scope, or unavailable evidence targets
|
|
|
|
components:
|
|
schemas:
|
|
ControlInterpretationVersion:
|
|
type: object
|
|
required:
|
|
- version_key
|
|
- display_label
|
|
properties:
|
|
version_key:
|
|
type: string
|
|
example: compliance_evidence_mapping.v1
|
|
display_label:
|
|
type: string
|
|
calm_disclosure:
|
|
type: string
|
|
nullable: true
|
|
|
|
PackageAvailabilityState:
|
|
type: object
|
|
description: Package-facing availability derived from the existing artifact-truth seam. Canonical mapping is publishable -> available, internal_only or stale -> partial, blocked or missing_input -> unavailable, historical_only -> expired, and package-level entitlement restriction -> blocked. Secondary-artifact restrictions do not force the top-level package state to blocked when the summary remains readable.
|
|
required:
|
|
- state
|
|
- message
|
|
properties:
|
|
state:
|
|
type: string
|
|
enum:
|
|
- available
|
|
- partial
|
|
- unavailable
|
|
- expired
|
|
- blocked
|
|
message:
|
|
type: string
|
|
reason_code:
|
|
type: string
|
|
nullable: true
|
|
description: Explains why the package is not fully available without creating a second availability taxonomy.
|
|
enum:
|
|
- current_review_pack_missing
|
|
- current_review_pack_expired
|
|
- stale_basis
|
|
- evidence_basis_partial
|
|
- interpretation_missing
|
|
- source_not_publishable
|
|
- entitlement_restricted
|
|
download_url:
|
|
type: string
|
|
nullable: true
|
|
|
|
SupportingArtifactLink:
|
|
type: object
|
|
description: Optional proof or artifact drilldown. A supporting link may be forbidden or unavailable while the top-level package summary remains readable.
|
|
required:
|
|
- artifact_family
|
|
- state
|
|
- label
|
|
properties:
|
|
artifact_family:
|
|
type: string
|
|
enum:
|
|
- review_pack
|
|
- evidence_snapshot
|
|
- stored_report
|
|
state:
|
|
type: string
|
|
enum:
|
|
- available
|
|
- partial
|
|
- unavailable
|
|
- expired
|
|
- redacted
|
|
- forbidden
|
|
label:
|
|
type: string
|
|
message:
|
|
type: string
|
|
nullable: true
|
|
url:
|
|
type: string
|
|
nullable: true
|
|
|
|
ManagementFindingHighlight:
|
|
type: object
|
|
required:
|
|
- label
|
|
- customer_summary
|
|
properties:
|
|
finding_id:
|
|
type: integer
|
|
nullable: true
|
|
label:
|
|
type: string
|
|
severity:
|
|
type: string
|
|
nullable: true
|
|
customer_summary:
|
|
type: string
|
|
control_key:
|
|
type: string
|
|
nullable: true
|
|
|
|
GovernanceDecisionFollowUp:
|
|
type: object
|
|
required:
|
|
- decision_source
|
|
- decision_state
|
|
- decision_summary
|
|
properties:
|
|
decision_source:
|
|
type: string
|
|
enum:
|
|
- finding_exception
|
|
- risk_acceptance
|
|
decision_state:
|
|
type: string
|
|
enum:
|
|
- awareness_required
|
|
- expiring
|
|
- expired
|
|
- revoked
|
|
- missing_basis
|
|
decision_summary:
|
|
type: string
|
|
accountable_label:
|
|
type: string
|
|
nullable: true
|
|
review_due_at:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
expires_at:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
|
|
GovernancePackageSummary:
|
|
type: object
|
|
required:
|
|
- review_id
|
|
- tenant_id
|
|
- interpretation
|
|
- delivery_artifact_family
|
|
- package_availability
|
|
- executive_summary
|
|
properties:
|
|
review_id:
|
|
type: integer
|
|
tenant_id:
|
|
type: integer
|
|
interpretation:
|
|
$ref: '#/components/schemas/ControlInterpretationVersion'
|
|
delivery_artifact_family:
|
|
type: string
|
|
enum:
|
|
- review_pack
|
|
package_availability:
|
|
$ref: '#/components/schemas/PackageAvailabilityState'
|
|
executive_summary:
|
|
type: string
|
|
highlights:
|
|
type: array
|
|
items:
|
|
type: string
|
|
top_findings:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/ManagementFindingHighlight'
|
|
accepted_risks:
|
|
type: array
|
|
description: Currently valid tolerated-risk positions that explain why material risk is presently accepted and does not require immediate stakeholder follow-up beyond awareness.
|
|
items:
|
|
$ref: '#/components/schemas/GovernanceDecisionFollowUp'
|
|
governance_decisions:
|
|
type: array
|
|
description: Accepted-risk or exception decision entries that still require stakeholder awareness or follow-up. Entries must be disjoint from accepted_risks for the same review.
|
|
items:
|
|
$ref: '#/components/schemas/GovernanceDecisionFollowUp'
|
|
evidence_basis_summary:
|
|
type: string
|
|
nullable: true
|
|
recommended_next_action:
|
|
type: string
|
|
nullable: true
|
|
supporting_artifacts:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/SupportingArtifactLink'
|
|
|
|
CustomerReviewWorkspaceEntry:
|
|
type: object
|
|
required:
|
|
- tenant_id
|
|
- tenant_name
|
|
- latest_published_review_id
|
|
- package_availability
|
|
- control_readiness
|
|
properties:
|
|
tenant_id:
|
|
type: integer
|
|
tenant_name:
|
|
type: string
|
|
latest_published_review_id:
|
|
type: integer
|
|
latest_review_published_at:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
interpretation:
|
|
$ref: '#/components/schemas/ControlInterpretationVersion'
|
|
package_availability:
|
|
$ref: '#/components/schemas/PackageAvailabilityState'
|
|
control_readiness:
|
|
type: string
|
|
evidence_basis:
|
|
type: string
|
|
nullable: true
|
|
recommended_next_action:
|
|
type: string
|
|
nullable: true
|
|
evidence_proof_state:
|
|
type: string
|
|
nullable: true
|
|
management_teaser:
|
|
type: string
|
|
nullable: true
|
|
|
|
CustomerReviewWorkspacePageModel:
|
|
type: object
|
|
required:
|
|
- workspace_id
|
|
- entries
|
|
properties:
|
|
workspace_id:
|
|
type: integer
|
|
tenant_filter_id:
|
|
type: integer
|
|
nullable: true
|
|
entries:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/CustomerReviewWorkspaceEntry'
|
|
|
|
GovernancePackageDetailModel:
|
|
type: object
|
|
required:
|
|
- review
|
|
- package
|
|
properties:
|
|
review:
|
|
type: object
|
|
required:
|
|
- review_id
|
|
- tenant_id
|
|
- published_at
|
|
properties:
|
|
review_id:
|
|
type: integer
|
|
tenant_id:
|
|
type: integer
|
|
published_at:
|
|
type: string
|
|
format: date-time
|
|
nullable: true
|
|
package:
|
|
$ref: '#/components/schemas/GovernancePackageSummary' |