ahmido
2bf53f6337
Some checks failed
Main Confidence / confidence (push) Failing after 44s
## Summary - enforce shared operation run link generation across admin and system surfaces - add guard coverage to block new raw operation route bypasses outside explicit exceptions - harden Filament theme asset resolution so stale or wrong-stack hot files fall back to built assets ## Testing - export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent - export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/OpsUx/CanonicalViewRunLinksTest.php tests/Feature/Monitoring/OperationsDashboardDrillthroughTest.php tests/Feature/Filament/RecentOperationsSummaryWidgetTest.php tests/Feature/Filament/InventoryCoverageRunContinuityTest.php tests/Feature/ReviewPack/ReviewPackResourceTest.php tests/Feature/144/CanonicalOperationViewerDeepLinkTrustTest.php tests/Feature/078/RelatedLinksOnDetailTest.php tests/Feature/RunAuthorizationTenantIsolationTest.php tests/Feature/System/Spec195/SystemDirectoryResidualSurfaceTest.php tests/Feature/System/Spec113/AuthorizationSemanticsTest.php tests/Feature/Guards/OperationRunLinkContractGuardTest.php tests/Unit/Filament/PanelThemeAssetTest.php Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #268
381 lines
13 KiB
YAML
381 lines
13 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: Operation Run Link Contract Enforcement
|
|
version: 1.0.0
|
|
summary: Logical internal contract for Spec 232 canonical admin and system operation-run links plus bounded guard enforcement.
|
|
description: |
|
|
This contract documents the internal helper-owned URL semantics that Spec 232 enforces.
|
|
It is intentionally logical rather than a public HTTP API because the feature reuses
|
|
existing Filament pages, helper families, and route ownership instead of introducing
|
|
a new controller namespace.
|
|
servers:
|
|
- url: https://logical.internal
|
|
description: Non-routable placeholder used to describe internal repository contracts.
|
|
paths:
|
|
/internal/operation-run-links/admin/collection:
|
|
post:
|
|
summary: Build the canonical admin operations collection URL for a covered source surface.
|
|
operationId: buildAdminOperationCollectionLink
|
|
x-not-public-http: true
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/vnd.tenantpilot.admin-operation-collection-input+json:
|
|
schema:
|
|
$ref: '#/components/schemas/AdminOperationCollectionLinkInput'
|
|
responses:
|
|
'200':
|
|
description: Canonical admin collection link emitted through `OperationRunLinks::index(...)`.
|
|
content:
|
|
application/vnd.tenantpilot.operation-link+json:
|
|
schema:
|
|
$ref: '#/components/schemas/CanonicalOperationLink'
|
|
/internal/operation-run-links/admin/detail:
|
|
post:
|
|
summary: Build the canonical admin operation detail URL for a covered source surface.
|
|
operationId: buildAdminOperationDetailLink
|
|
x-not-public-http: true
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/vnd.tenantpilot.admin-operation-detail-input+json:
|
|
schema:
|
|
$ref: '#/components/schemas/AdminOperationDetailLinkInput'
|
|
responses:
|
|
'200':
|
|
description: Canonical admin detail link emitted through `OperationRunLinks::view(...)` or `tenantlessView(...)`.
|
|
content:
|
|
application/vnd.tenantpilot.operation-link+json:
|
|
schema:
|
|
$ref: '#/components/schemas/CanonicalOperationLink'
|
|
/internal/operation-run-links/system/collection:
|
|
post:
|
|
summary: Build the canonical system operations collection URL for a covered system source surface.
|
|
operationId: buildSystemOperationCollectionLink
|
|
x-not-public-http: true
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/vnd.tenantpilot.system-operation-collection-input+json:
|
|
schema:
|
|
$ref: '#/components/schemas/SystemOperationCollectionLinkInput'
|
|
responses:
|
|
'200':
|
|
description: Canonical system collection link emitted through `SystemOperationRunLinks::index()`.
|
|
content:
|
|
application/vnd.tenantpilot.operation-link+json:
|
|
schema:
|
|
$ref: '#/components/schemas/CanonicalOperationLink'
|
|
/internal/operation-run-links/system/detail:
|
|
post:
|
|
summary: Build the canonical system operation detail URL for a covered system source surface.
|
|
operationId: buildSystemOperationDetailLink
|
|
x-not-public-http: true
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/vnd.tenantpilot.system-operation-detail-input+json:
|
|
schema:
|
|
$ref: '#/components/schemas/SystemOperationDetailLinkInput'
|
|
responses:
|
|
'200':
|
|
description: Canonical system detail link emitted through `SystemOperationRunLinks::view(...)`.
|
|
content:
|
|
application/vnd.tenantpilot.operation-link+json:
|
|
schema:
|
|
$ref: '#/components/schemas/CanonicalOperationLink'
|
|
/internal/guards/operation-run-link-contract/check:
|
|
post:
|
|
summary: Scan the bounded app-side source surface for raw operation-run link bypasses.
|
|
operationId: checkOperationRunLinkContract
|
|
x-not-public-http: true
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/vnd.tenantpilot.operation-run-link-guard-input+json:
|
|
schema:
|
|
$ref: '#/components/schemas/OperationRunLinkGuardCheck'
|
|
responses:
|
|
'200':
|
|
description: Guard completed and found no violations inside the declared boundary.
|
|
content:
|
|
application/vnd.tenantpilot.operation-run-link-guard-report+json:
|
|
schema:
|
|
$ref: '#/components/schemas/OperationRunLinkGuardReport'
|
|
'422':
|
|
description: Guard found one or more raw bypasses outside the allowlist.
|
|
content:
|
|
application/vnd.tenantpilot.operation-run-link-guard-report+json:
|
|
schema:
|
|
$ref: '#/components/schemas/OperationRunLinkGuardReport'
|
|
/admin/operations:
|
|
get:
|
|
summary: Existing canonical admin operations collection route.
|
|
operationId: openAdminOperationsCollection
|
|
responses:
|
|
'200':
|
|
description: Admin monitoring collection renders for an entitled workspace operator.
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Actor is in scope but lacks the required capability.
|
|
'404':
|
|
description: Actor is not entitled to the workspace or tenant-bound records referenced by the current context.
|
|
/admin/operations/{run}:
|
|
get:
|
|
summary: Existing canonical admin operation detail route.
|
|
operationId: openAdminOperationDetail
|
|
parameters:
|
|
- name: run
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Canonical admin run detail renders for an entitled operator.
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Actor is a member in scope but lacks current capability.
|
|
'404':
|
|
description: Actor cannot access the run because of workspace, tenant, or plane isolation.
|
|
/system/ops/runs:
|
|
get:
|
|
summary: Existing canonical system operations collection route.
|
|
operationId: openSystemOperationsCollection
|
|
responses:
|
|
'200':
|
|
description: System monitoring collection renders for an entitled platform user.
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Platform user lacks the required system operations capability.
|
|
'404':
|
|
description: Actor is not entitled to the system plane.
|
|
/system/ops/runs/{run}:
|
|
get:
|
|
summary: Existing canonical system operation detail route.
|
|
operationId: openSystemOperationDetail
|
|
parameters:
|
|
- name: run
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
responses:
|
|
'200':
|
|
description: Canonical system run detail renders for an entitled platform user.
|
|
content:
|
|
text/html:
|
|
schema:
|
|
type: string
|
|
'403':
|
|
description: Platform user lacks the required system operations capability.
|
|
'404':
|
|
description: Actor is not entitled to the system plane or the run is not visible there.
|
|
components:
|
|
schemas:
|
|
OperationPlane:
|
|
type: string
|
|
enum:
|
|
- admin
|
|
- system
|
|
OperationLinkKind:
|
|
type: string
|
|
enum:
|
|
- collection
|
|
- detail
|
|
CoveredSurfaceKey:
|
|
type: string
|
|
description: Stable identifier for the source surface that emits the canonical link.
|
|
CanonicalNavigationContextInput:
|
|
type: object
|
|
description: |
|
|
Opaque helper-owned navigation context payload passed through the admin helper family
|
|
when a source surface needs canonical back-link or query continuity.
|
|
additionalProperties: true
|
|
AdminOperationCollectionLinkInput:
|
|
type: object
|
|
required:
|
|
- surfaceKey
|
|
properties:
|
|
surfaceKey:
|
|
$ref: '#/components/schemas/CoveredSurfaceKey'
|
|
tenantId:
|
|
type: integer
|
|
tenantExternalId:
|
|
type: string
|
|
navigationContext:
|
|
$ref: '#/components/schemas/CanonicalNavigationContextInput'
|
|
activeTab:
|
|
type: string
|
|
problemClass:
|
|
type: string
|
|
operationType:
|
|
type: string
|
|
description: Optional helper-owned operations table type filter, used by inventory coverage history links.
|
|
allTenants:
|
|
type: boolean
|
|
default: false
|
|
description: Canonical input for `OperationRunLinks::index(...)`.
|
|
AdminOperationDetailLinkInput:
|
|
type: object
|
|
required:
|
|
- surfaceKey
|
|
- runId
|
|
properties:
|
|
surfaceKey:
|
|
$ref: '#/components/schemas/CoveredSurfaceKey'
|
|
runId:
|
|
type: integer
|
|
navigationContext:
|
|
$ref: '#/components/schemas/CanonicalNavigationContextInput'
|
|
description: Canonical input for `OperationRunLinks::view(...)` or `tenantlessView(...)`.
|
|
SystemOperationCollectionLinkInput:
|
|
type: object
|
|
required:
|
|
- surfaceKey
|
|
properties:
|
|
surfaceKey:
|
|
$ref: '#/components/schemas/CoveredSurfaceKey'
|
|
description: Canonical input for `SystemOperationRunLinks::index()`.
|
|
SystemOperationDetailLinkInput:
|
|
type: object
|
|
required:
|
|
- surfaceKey
|
|
- runId
|
|
properties:
|
|
surfaceKey:
|
|
$ref: '#/components/schemas/CoveredSurfaceKey'
|
|
runId:
|
|
type: integer
|
|
description: Canonical input for `SystemOperationRunLinks::view(...)`.
|
|
CanonicalOperationLink:
|
|
type: object
|
|
required:
|
|
- label
|
|
- url
|
|
- plane
|
|
- kind
|
|
- canonicalNoun
|
|
properties:
|
|
label:
|
|
type: string
|
|
url:
|
|
type: string
|
|
plane:
|
|
$ref: '#/components/schemas/OperationPlane'
|
|
kind:
|
|
$ref: '#/components/schemas/OperationLinkKind'
|
|
canonicalNoun:
|
|
type: string
|
|
example: Operation
|
|
preservedQueryKeys:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Helper-owned operator-facing link output for canonical operations destinations.
|
|
OperationRunLinkGuardCheck:
|
|
type: object
|
|
required:
|
|
- includePaths
|
|
- allowlistedPaths
|
|
- forbiddenPatterns
|
|
properties:
|
|
includePaths:
|
|
type: array
|
|
items:
|
|
type: string
|
|
examples:
|
|
- - app/Filament/Widgets/Tenant/RecentOperationsSummary.php
|
|
- app/Filament/Pages/InventoryCoverage.php
|
|
- app/Filament/Resources/InventoryItemResource.php
|
|
- app/Filament/Resources/ReviewPackResource.php
|
|
- app/Filament/Pages/Operations/TenantlessOperationRunViewer.php
|
|
- app/Support/Navigation/RelatedNavigationResolver.php
|
|
- app/Filament/System/Pages/Directory/ViewTenant.php
|
|
- app/Filament/System/Pages/Directory/ViewWorkspace.php
|
|
- app/Filament/System/Pages/Ops/Runs.php
|
|
- app/Filament/System/Pages/Ops/ViewRun.php
|
|
- app/Providers/Filament/AdminPanelProvider.php
|
|
- app/Providers/Filament/TenantPanelProvider.php
|
|
- app/Support/Middleware/EnsureFilamentTenantSelected.php
|
|
- app/Http/Controllers/ClearTenantContextController.php
|
|
- app/Support/OpsUx/OperationRunUrl.php
|
|
allowlistedPaths:
|
|
type: array
|
|
items:
|
|
type: string
|
|
examples:
|
|
- - app/Providers/Filament/AdminPanelProvider.php
|
|
- app/Providers/Filament/TenantPanelProvider.php
|
|
- app/Support/Middleware/EnsureFilamentTenantSelected.php
|
|
- app/Http/Controllers/ClearTenantContextController.php
|
|
forbiddenPatterns:
|
|
type: array
|
|
items:
|
|
type: string
|
|
examples:
|
|
- - "route('admin.operations.index'"
|
|
- "route('admin.operations.view'"
|
|
- "/system/ops/runs"
|
|
- "Runs::getUrl("
|
|
- "ViewRun::getUrl("
|
|
acceptedDelegates:
|
|
type: array
|
|
items:
|
|
type: string
|
|
examples:
|
|
- - app/Support/OpsUx/OperationRunUrl.php
|
|
description: Declares the bounded source surface and explicit exceptions for the guard.
|
|
OperationRunLinkGuardViolation:
|
|
type: object
|
|
required:
|
|
- filePath
|
|
- line
|
|
- snippet
|
|
- reason
|
|
properties:
|
|
filePath:
|
|
type: string
|
|
line:
|
|
type: integer
|
|
snippet:
|
|
type: string
|
|
expectedHelper:
|
|
type: string
|
|
reason:
|
|
type: string
|
|
description: Actionable failure output for one raw bypass.
|
|
OperationRunLinkGuardReport:
|
|
type: object
|
|
required:
|
|
- scannedPaths
|
|
- allowlistedPaths
|
|
- violations
|
|
properties:
|
|
scannedPaths:
|
|
type: array
|
|
items:
|
|
type: string
|
|
allowlistedPaths:
|
|
type: array
|
|
items:
|
|
type: string
|
|
acceptedDelegates:
|
|
type: array
|
|
items:
|
|
type: string
|
|
violations:
|
|
type: array
|
|
items:
|
|
$ref: '#/components/schemas/OperationRunLinkGuardViolation'
|
|
description: Report shape returned by the bounded guard check.
|