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.

Also pin the docker/registry links to a specific version so the links
will survive future docker/registry changes (including removing the
docs after the OCI picks them up).  As long as the TOB-selected
version isn't far behind (how far will the spec move during a week of
voting?), it should be easy for the new maintainets to catch up on any
subsequent drift.

The signing scope language is from Stephen in [5].  The discovery
scope language is from Derek [6].

[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
[5]: opencontainers#35 (comment)
[6]: opencontainers#34 (comment)

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

Author: wking

proposals/distribution.md

@@ -1,19 +1,25 @@
 # 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).
 
 In the past when the topic of having an OCI specification around the distribution of container images was discussed, it was deferred as "let’s get the image format defined, meanwhile the industry will settle on a distribution standard". Fast forward, OCI image format is out and adopted, and the Registry v2 is the defacto standard. There is and will be use-cases for alternate methods and the future will likely hold creative ways to push, fetch and share container images, but right now this promotion serves to acknowledge by the OCI the current industry standard of distributing container images.
 
 There is polish that is needed e.g. broken links to storage-driver docs, as well as making sections more generic regarding the OCI descriptors and media-types, but on the whole this is a lateral move.
 
+This project is scoped to cover the client ↔ registry and client ↔ auth-server interactions.  The following are out of scope:
+
+* Registry ↔ auth-server interaction.  Token creation and parsing do not impact clients, for whom tokens are opaque strings.
+* Signing.  All resources are content-addressable and can be signed in external systems.
+* Discovery.  Discovery and registry are completely separate and do not need to be added together.
+
 ## Initial Maintainers
 
 * Stephen Day <[email protected]> (@stevvooe)
@@ -64,3 +70,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