distribution: Also move the Bearer token and OAuth docs

Docker's use of Bearer requires information beyond what's covered in
RFC 6749 and 6750 [1].  So folks writing a client that will interact
with a Docker registry that uses that auth approach will need a
"Docker registry's 'Bearer' additions" spec to follow.  While I prefer
off-the-shelf RFCs for HTTP auth, the Docker registry additions are
small enough, and widely used.  This change adds the client side of
their specification to the new distribution-spec project.

The docker/distribution repository also includes docs for scope [3]
and the JWT token semantics [4].  The scope docs are borderline useful
for clients, but I've left them out because clients can extract the
required scope from WWW-Authenticate in 401ed responses:

  $ curl -IH 'Accept: application/vnd.docker.distribution.manifest.v2+json' https://index.docker.io/v2/library/docker/manifests/1.12.1
  HTTP/1.1 401 Unauthorized
  Content-Type: application/json; charset=utf-8
  Docker-Distribution-Api-Version: registry/2.0
  Www-Authenticate: Bearer realm="https://auth.docker.io/token",service="registry.docker.io",scope="repository:library/docker:pull"
  ...

Clients can consider them opaque, so I've left them out of the
distribution-spec project for now.  If distribution-spec maintainers
feel that clients could benefit by explicitly crafting their own scope
strings, they can pull in the scope specification after the project
forms.

JWT token semantics [4] are part of the interface between the auth
server and the registry.  Clients can consider them opaque, so I've
left them out of the distribution-spec project.

[1]: xiekeyang/oci-discovery#64 (comment)
[2]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/auth/oauth.md
[3]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/auth/scope.md
[4]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/auth/jwt.md

Signed-off-by: W. Trevor King <[email protected]>

Author: wking

proposals/distribution.md

@@ -1,12 +1,12 @@
 # Abstract
 
-The Docker registry protocol has become the defacto standard across the container registry world ([https://github.com/docker/distribution/blob/master/docs/spec/api.md](https://github.com/docker/distribution/blob/master/docs/spec/api.md)).
+The Docker registry protocol has become the defacto standard across the container registry world.
 
 In the OCI, having a solid, common distribution specification with conformance testing will ensure long lasting security and interoperability throughout the container ecosystem.
 
 ## Proposal
 
-TL;DR; Move [https://github.com/docker/distribution/tree/master/docs/spec](https://github.com/docker/distribution/tree/master/docs/spec) to [https://github.com/opencontainers/distribution-spec](https://github.com/opencontainers/distribution-spec)
+TL;DR; Move [`api.md`][api.md], [`token.md`][token.md], and [`oauth.md`][oauth.md] to a new [distribution-spec project](https://github.com/opencontainers/distribution-spec).
 
 This proposal covers the distribution API spec, and while it does not cover the code for the docker-registry, that implementation is considered the reference implementation. There are other implementations of this protocol, not all are open-source though (Google gcr.io, Amazon ECR, CoreOS Quay, Gitlab registry, JFrog Artifactory registry, Huawei Dockyard, etc).
 
@@ -64,3 +64,7 @@ The API spec is currently considered v2 and we will start the specification at v
 
 * Simplifies tag listing: docker/distribution#2169
 * Allows listing of manifests: docker/distribution#2199
+
+[api.md]: https://github.com/docker/distribution/blob/cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/api.md
+[oauth.md]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/auth/oauth.md
+[token.md]: https://github.com/docker/distribution/blob/5cb406d511b7b9163bff9b6439072e4892e5ae3b/docs/spec/auth/token.md