Add requirements or recommendations about allow/deny lists for reference target retrieval

[handrews]

As multi-document OADs become more important due to both new use cases and an increasing number of OADs that are far too large to work with as a single document, we should be more clear about the resource location and retrieval process.

In particular, there is a security risk to fetching resources from arbitrary locations. We should at least RECOMMEND some sort of allow/deny functionality, and require (MUST) a sensible default behavior.

For example, it's conceivable that a poorly designed API runtime tool running at improperly elevated privilege could be induced to load a sensitive file, get confused, and display it in an error message over the network. Or, a tool that does something bad like eval() fetched JSON could be sent a malicious bit of JavaScript instead.

[miqui]

@handrews If you have something like this:

paths:
  /users:
    get:
      summary: Get all users
      responses:
        '200':
          $ref: './components/responses.yaml#/UserListResponse'

How does your proposal work in this split, but local file example? I like your idea btw.

[handrews]

@miqui First I want to make clear that I do not want to mandate any specific pre-determiend allow/deny configuration (except that I think the default should be "deny all" and you should have to configure either a specific allow list or "allow all", which should probably be named "enable gaping security hole") ;-P

We could encourage some "sensible" common configurations, like "anything in this (local or remote) directory or any subdirectory of it is allowed." That's would handle the very typical configuraiton where the entry document is in a directory, and the "split" documents are in sub-directories mirroring the intended JSON/YAML structure of the un-split document. That would place the $ref in your example within the allowed reference target scope.

But (if that is the only allow-rule), if someone changed it to $ref: https://this-is-a-bad-place.com/malware.yaml, attempts to resolve that changed reference would fail.

[handrews]

I'm OK with bumping this out of 3.2. Let's get $self out there first, as that is what makes this feature make more sense (because it allows resolving refs without any external I/O if you make all documents available up front).