openapi: 3.1.0
info:
  title: Workspace-first RBAC & Environment Access Scoping (Logical Contract)
  version: 0.1.0
  description: >-
    Logical review contract for Feature 285. These endpoints model the shared
    access decisions the runtime implementation must be able to answer. They do
    not require public HTTP exposure in their current form.
servers:
  - url: https://tenantpilot.local/logical
paths:
  /workspaces/{workspaceId}/members/{userId}/authorization:
    get:
      operationId: getWorkspaceMembershipAuthorizationSummary
      summary: Return the canonical workspace-role authorization summary for one member.
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Workspace membership summary
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkspaceMembershipAuthorizationSummary'
  /workspaces/{workspaceId}/managed-environments/{managedEnvironmentId}/authorization/{userId}:
    get:
      operationId: getManagedEnvironmentAuthorizationDecision
      summary: >-
        Return the workspace-first authorization decision for one managed
        environment and one user.
      parameters:
        - $ref: '#/components/parameters/WorkspaceId'
        - $ref: '#/components/parameters/ManagedEnvironmentId'
        - $ref: '#/components/parameters/UserId'
        - name: requiredCapability
          in: query
          required: false
          schema:
            type: string
          description: Existing capability key required by the calling surface.
      responses:
        '200':
          description: Managed-environment authorization decision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManagedEnvironmentAuthorizationDecision'
  /operation-runs/{operationRunId}/authorization/{userId}:
    get:
      operationId: getOperationRunAuthorizationDecision
      summary: Return the workspace-first authorization decision for one operation run.
      parameters:
        - $ref: '#/components/parameters/OperationRunId'
        - $ref: '#/components/parameters/UserId'
      responses:
        '200':
          description: Operation-run authorization decision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationRunAuthorizationDecision'
components:
  parameters:
    WorkspaceId:
      name: workspaceId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    ManagedEnvironmentId:
      name: managedEnvironmentId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    OperationRunId:
      name: operationRunId
      in: path
      required: true
      schema:
        type: string
        format: uuid
    UserId:
      name: userId
      in: path
      required: true
      schema:
        type: string
        format: uuid
  schemas:
    WorkspaceMembershipAuthorizationSummary:
      type: object
      additionalProperties: false
      required:
        - workspace_id
        - user_id
        - workspace_member
        - owner_guarded
      properties:
        workspace_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        workspace_member:
          type: boolean
        workspace_role:
          type:
            - string
            - 'null'
          description: Role value resolved from the canonical workspace membership.
        owner_guarded:
          type: boolean
          description: Indicates whether last-owner protection applies to this member.
    ManagedEnvironmentAuthorizationDecision:
      type: object
      additionalProperties: false
      required:
        - workspace_id
        - managed_environment_id
        - user_id
        - workspace_member
        - explicit_scope_rows_present
        - managed_environment_allowed
        - capability_allowed
      properties:
        workspace_id:
          type: string
          format: uuid
        managed_environment_id:
          type: string
          format: uuid
        user_id:
          type: string
          format: uuid
        workspace_member:
          type: boolean
        workspace_role:
          type:
            - string
            - 'null'
        explicit_scope_rows_present:
          type: boolean
          description: >-
            False means the member inherits environment visibility across the
            currently selectable managed environments in the workspace. True
            means visibility is narrowed by an allowlist.
        managed_environment_allowed:
          type: boolean
        failed_boundary:
          type:
            - string
            - 'null'
          description: >-
            Derived denial boundary such as workspace_membership,
            managed_environment_scope, or capability when access is denied.
        required_capability:
          type:
            - string
            - 'null'
        capability_allowed:
          type: boolean
        denial_http_status:
          type:
            - integer
            - 'null'
          description: 404 for non-membership or out-of-scope access, 403 for missing capability.
        provider_capability_context:
          type:
            - string
            - 'null'
          description: Optional downstream provider-capability note; local RBAC resolves before this.
    OperationRunAuthorizationDecision:
      type: object
      additionalProperties: false
      required:
        - operation_run_id
        - workspace_id
        - user_id
        - workspace_member
        - managed_environment_allowed
        - capability_allowed
      properties:
        operation_run_id:
          type: string
          format: uuid
        workspace_id:
          type: string
          format: uuid
        managed_environment_id:
          type:
            - string
            - 'null'
          format: uuid
        user_id:
          type: string
          format: uuid
        workspace_member:
          type: boolean
        workspace_role:
          type:
            - string
            - 'null'
        managed_environment_allowed:
          type: boolean
          description: >-
            Always true for workspace-bound runs with no managed environment;
            otherwise derived from the managed-environment access decision.
        failed_boundary:
          type:
            - string
            - 'null'
          description: >-
            Derived denial boundary such as workspace_membership,
            managed_environment_scope, or capability when access is denied.
        required_capability:
          type:
            - string
            - 'null'
        capability_allowed:
          type: boolean
        denial_http_status:
          type:
            - integer
            - 'null'