Tap14 updates

tap14.md

@@ -163,6 +163,8 @@ with a directory for each supported TUF specification version. These directories
 contain metadata that supports the given TUF specification version. Using these
 directories, a client is able to choose the most recent metadata they support.
 More details about this directory structure are contained in the [specification](#how-a-repository-updates).
+The repository may also maintain a `supported-versions.json` file so that the client
+can discover the supported specification versions on the repository.
 
 On the client side, this TAP also requires maintenance of multiple versions that
 support different major TUF specification
@@ -178,7 +180,8 @@ version. A specification change may rely on more than one metadata file (for
 example a change in the signing process would affect all metadata types), so
 using the same specification version for top-level metadata allows for these
 large changes to the specification. For information about how this relates to
-url pinning and TAP 5, see [Special Cases](#tap-5). However, delegated targets metadata may not be
+targets metadata pinning and TAP 13, see [Special Cases](#tap-13). However,
+delegated targets metadata might not be
 managed by the same parties as the top-level metadata. For this reason, this TAP
 allows clients to use a different TUF specification version for delegated
 targets by maintaining functions to parse metadata that conforms to different
@@ -234,6 +237,7 @@ small changes to existing features. More details about what constitutes a major,
 minor, or patch change can be found at https://semver.org/.
 
 ### Changes to TAPs
+
 In order to manage changes to TUF, TAPs shall be tied to a version of the TUF
 specification.
 
@@ -244,14 +248,16 @@ has been updated to include the TUF Version field.
 
 ## How a repository updates
 
-Repositories will add metadata for new TUF specification versions in new
-directories.
+Repositories will add two things. They MUST put metadata for new TUF
+specification versions in new
+directories. In addition, repositories SHOULD maintain a `supported-versions.json` file
+to indicate which specification versions are supported.
 
 As described in the [Rationale](#rationale), repositories should support multiple
 TUF specification versions. In order to do so, this TAP proposes a new directory
 structure for repositories. When a repository manager chooses to upgrade to a
 new major TUF specification version, they create a new directory on the repository named
-for the major version (for example 2.0.0). This directory will contain all
+for the major version (for example 2). This directory will contain all
 metadata files for the new specification version, but target files will remain in the
 parent directory to save space. In this case the metadata files (in directories according to their spec
 version) can point to target files relative to the parent directory. After creating
@@ -266,16 +272,16 @@ version 2.0.0, the repository structure may look like:
 
 ```
 - Target files
-- 1.0.0
+- 1
   |- metadata files
-- 2.0.0
+- 2
   |- metadata files
 ```
 
 Repository updates to a new minor or patch specification version shall be done
 by uploading new metadata files in the new format to the proper directory. So if
 a repository updates from 2.0.0 to 2.1.0, the 2.1.0 metadata would go in the
-directory named 2.0.0. Minor and patch version changes are backwards compatible,
+directory named 2. Minor and patch version changes are backwards compatible,
 so clients using version 2.0.0 will still be able to parse metadata written
 using version 2.1.0.
 
@@ -342,24 +348,47 @@ TUF versions that the repository supports. Any update should be reflected across
 all of these versions. For clarity, version numbers used for consistent
 snapshots should be consistent across all
 supported specification versions so that a client can find the current
-metadata files. This means that there may be a file at 1.0.0/3.root.json as well
-as 2.0.0/3.root.json. Root metadata files with the same consistent snapshot number must
+metadata files. This means that there may be a file at 1/3.root.json as well
+as 2/3.root.json. Root metadata files with the same consistent snapshot number must
 also use the same keys so that a client can find the next root metadata file in whichever
 specification version they support.
 
 For existing TUF clients to continue operation after this TAP is implemented,
 repositories may store metadata from before TUF 2.0.0 in the top-level
-repository (with no directory named 1.0.0). This allows existing clients to
+repository (with no directory named 1). This allows existing clients to
 continue downloading metadata from the repository. So a TUF repository that
-upgrades from version 1.0.0 to version 2.0.0 may look like:
+upgrades from version 1.x.x to version 2.0.0 may look like:
 
 
 ```
 - Targets files
-- 1.0.0 metadata files
-- 2.0.0
-  |- 2.0.0 metadata files
+- 1.x.x metadata files
+- 2
+  |- 2.x.x metadata files
+```
+
+Not all TUF repositories have a mechanism that is  able to list all directories
+in a folder (the equivalent of the `ls` command). For these repositories (such
+as OCI registries or http servers), the repository SHOULD include a
+`supported-versions.json` file in the top of this directory structure that lists
+all versions supported by the repository to allow for client discovery. This file
+will be signed by a threshold of root keys, and the `signed` portion will have
+the following fields:
+
 ```
+{ "supported_versions" : [
+    { MAJOR_VERSION: FOLDER_NAME},
+    ...
+  ]
+}
+
+```
+
+where `MAJOR_VERSION` is the integer representing a supported major version (i.e. 2)
+and `FOLDER_NAME` is the string representing the folder containing metadata for
+this supported major version. In most cases, `MAJOR_VERSION` should match `FOLDER_NAME`.
+For backwards compatability, version 1 should be assumed to be in the top-level
+repository with no directory named 1.
 
 ## Changes to TUF clients
 
@@ -397,7 +426,8 @@ the client looks for the highest supported version on the repository using the
 following procedure:
 
 * The client determines the latest version available on the repository by
-looking for the directory with the largest version number.
+looking for the directory with the largest version number, or by parsing the
+`supported-versions.json` file.
 * If the latest version on the repository is lower than the previous
 specification version the client used from this repository, the client
 should report an error and terminate the update.
@@ -418,13 +448,13 @@ Once the supported directory is determined, the client shall attempt the update
 using the metadata in this directory.
 
 For example, if a client has a specification version of 3.5 and a repository has
-directories for 2.0.0, 3.0.0, and 4.0.0, the client will report that spec
-version 4.x is available, then download metadata from the 3.0.0 directory. This reporting is
-up to the discretion of an implementer, but it should be used to encourage
+directories for 2, 3, and 4, the client will report that spec
+version 4.x is available, then download metadata from the 3 directory. This reporting is
+up to the discretion of each application, but it should be used to encourage
 updating the client to the most recent specification version.
 
 Alternatively, if the same client downloads metadata from a repository with
-directories 1.0.0 and 2.0.0, the client could download metadata from 2.0.0 using
+directories 1 and 2, the client could download metadata from 2 using
 a 2.x version of the client. If 2.x is not supported by the client, the client
 will report that it is unable to perform an update.
 
@@ -441,7 +471,7 @@ major version of the root file.
 
 So, if the currently trusted root file is named 4.root.json and uses version
 1.0.0 and the highest supported version is 3.0.0, the client will look for
-5.root.json first in 3.0.0, then 2.0.0, then 1.0.0. If this file is found, the
+5.root.json first in 3, then 2, then 1. If this file is found, the
 client will look for 6.root.json using the same process. To facilitate this, the
 client should maintain functions to parse root files from previous spec
 versions. If the client does not support the specification version of a root file, the
@@ -478,25 +508,26 @@ provided by each repository. Note that different TUF versions may use different
 hashing algorithms. If this is the case, both hashes should be verified
 independently.
 
-### TAP 5
+### TAP 13
 
-A TUF client that supports TAP 5 may download top-level metadata from multiple
-sources. However, breaking changes may require that multiple top-level metadata
-files use the same TUF specification version. To manage this, a root metadata
-file that includes a list of urls for metadata as described in TAP 5 should
-only include links to metadata files using the same TUF specification version as
-the root metadata file.
+A TUF client that supports TAP 13 may download targets metadata that were
+uploaded by different parties.
+However, breaking changes may require that all top-level metadata
+files use the same TUF specification version. To manage this, a client
+configuration file that lists a custom top-level targets metadata file
+as described in TAP 13 should only include targets metadata files using the
+same TUF specification version as the root metadata file.
 
-The owner of root metadata is responsible for ensuring that all metadata files
-linked in the root metadata use the same TUF specification version as the root
+The owner of the client configuration is responsible for ensuring that any
+custom targets metadata files use the same TUF specification version as the root
 metadata. If the repository that contains the root metadata supports multiple
-TUF specification versions, each root metadata file should list top-level
-metadata corresponding with its TUF specification version.
+TUF specification versions, the client configuration should list a targets metadata
+file that is available in all supported specification versions.
 
 Clients should verify that all top-level metadata use the same TUF specification
-version as the root metadata. If a metadata file linked in root metadata does
-not meet this criteria, it will be considered invalid and the client should
-use the next listed metadata file or terminate the update.
+version as the root metadata. If a metadata file provided by the TAP 13 configuration
+does not meet this criteria, it will be considered invalid and the client should
+terminate the update.
 
 ### Delegations
 
@@ -529,7 +560,9 @@ attacks and changes to the security model that should be discussed.
 A downgrade attack on the TUF specification version may be possible if an
 attacker is able to block access to a directory on the repository. This would
 mean that a client would use metadata from a previous specification version when
-performing an update. However, the metadata would still have to be current and
+performing an update. Similarly, an attacker on the repository could replace the
+`supported-versions.json` file to remove the most recent specification version.
+However, in both of these cases the metadata would still have to be current and
 properly signed.
 
 Clients that have previously used a repository will store the specification