openapi: 3.1.0
info:
  title: Trusted State Hardening Logical Contract
  version: 0.1.0
  summary: Internal logical contract for protected actions on stateful Livewire and Filament surfaces
  description: |
    This contract documents the server-side trust boundary for covered stateful
    surfaces. It is semantic, not transport-prescriptive. Existing Filament and
    Livewire handlers may satisfy this contract without adding public HTTP endpoints.
    The first slice distinguishes presentation-only selector proposals, locked
    scalar continuity identities, and server-derived authority that must be
    re-resolved before every protected action.
servers:
  - url: /admin
  - url: /system
paths:
  /onboarding/{onboardingDraft}/verify-access:
    post:
      summary: Start or rerun verify access from a trusted onboarding draft context
      operationId: trustedOnboardingVerifyAccess
      parameters:
        - $ref: '#/components/parameters/OnboardingDraftId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                selected_provider_connection_id:
                  type: integer
                  nullable: true
                  description: Mutable selector proposal that must be revalidated within the current draft scope.
      responses:
        '202':
          description: Request accepted against canonical draft and provider scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrustedActionAccepted'
        '403':
          description: Actor is in scope but lacks the required capability.
        '404':
          description: Draft or provider selection is out of scope or not entitled.

  /onboarding/{onboardingDraft}/activate:
    post:
      summary: Activate a trusted onboarding draft
      operationId: trustedOnboardingActivate
      parameters:
        - $ref: '#/components/parameters/OnboardingDraftId'
      responses:
        '200':
          description: Activation executed against canonical draft truth.
        '403':
          description: Actor is in scope but lacks activation authority.
        '404':
          description: Draft is missing, stale, or foreign to the current workspace or tenant scope.

  /tenants/{tenant}/required-permissions:
    get:
      summary: Read required permissions from a route-derived tenant scope
      operationId: trustedTenantRequiredPermissionsRead
      parameters:
        - $ref: '#/components/parameters/TenantRouteKey'
        - in: query
          name: status
          schema:
            type: string
        - in: query
          name: type
          schema:
            type: string
        - in: query
          name: features[]
          schema:
            type: array
            items:
              type: string
        - in: query
          name: search
          schema:
            type: string
      responses:
        '200':
          description: Tenant-scoped page rendered from canonical route and workspace context.
        '404':
          description: Tenant is outside the current workspace or tenant entitlement scope.

  /ops/runbooks/findings-lifecycle/preflight:
    post:
      summary: Preflight a system runbook with validated selector scope
      operationId: trustedRunbookPreflight
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunbookScopeProposal'
      responses:
        '200':
          description: Preflight completed for an allowed scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunbookPreflightAccepted'
        '403':
          description: Platform actor lacks the required runbook capability.
        '404':
          description: Selected tenant is outside the actor's allowed tenant universe.

components:
  parameters:
    OnboardingDraftId:
      name: onboardingDraft
      in: path
      required: true
      schema:
        type: integer
    TenantRouteKey:
      name: tenant
      in: path
      required: true
      schema:
        type: string
  schemas:
    TrustedActionAccepted:
      type: object
      additionalProperties: false
      required:
        - authority_source
        - target_scope
      properties:
        authority_source:
          type: string
          enum:
            - route_binding
            - persisted_onboarding_draft
            - workspace_context
            - explicit_scoped_query
        target_scope:
          type: object
          additionalProperties: false
          required:
            - workspace_id
          properties:
            workspace_id:
              type: integer
            tenant_id:
              type: integer
              nullable: true
            provider_connection_id:
              type: integer
              nullable: true
        trusted_state_class:
          type: string
          enum:
            - locked_identity
            - server_derived_authority
    RunbookScopeProposal:
      type: object
      additionalProperties: false
      required:
        - mode
      properties:
        mode:
          type: string
          enum:
            - all_tenants
            - single_tenant
        tenant_id:
          type: integer
          nullable: true
    RunbookPreflightAccepted:
      type: object
      additionalProperties: false
      required:
        - resolved_scope
      properties:
        resolved_scope:
          type: object
          additionalProperties: false
          required:
            - mode
          properties:
            mode:
              type: string
              enum:
                - all_tenants
                - single_tenant
            tenant_id:
              type: integer
              nullable: true
            trusted_state_class:
              type: string
              enum:
                - server_derived_authority