feat: add port as mandatory TEI element

Signed-off-by: Pavel Shukhman <[email protected]>

Author: taleodor

discovery/readme.md

@@ -70,12 +70,13 @@ barcode and one with the vendor's product number.
 The TEI consists of three core parts
 
 ```text
-urn:tei:<type>:<domain-name>:<unique-identifier>
+urn:tei:<type>:<domain-name>:<domain-port>:<unique-identifier>
 ````
 
 - The **`type`** which defines the syntax of the unique identifier part
 - The **`domain-name`** part resolves into a web server, which may not be the API host.
   - The uniqueness of the name is the domain name part that has to be registred at creation of the TEI.
+- The **`domain-port`** is the port number of the web server on which ./well-known/tea is available.
 - The **`unique-identifier`** has to be unique within the `domain-name`.
   Recommendation is to use a UUID but it can be an existing article code too
 
@@ -94,13 +95,13 @@ Where the `unique-identifier` is a PURL in it's canonical string form.
 Syntax:
 
 ```text
-urn:tei:purl:<domain-name>:<purl>
+urn:tei:purl:<domain-name>:<domain-port>:<purl>
 ````
 
 Example:
 
 ```text
-urn:tei:purl:cyclonedx.org:pkg:pypi/[email protected]?extension=whl&qualifier=py3-none-any
+urn:tei:purl:cyclonedx.org:443:pkg:pypi/[email protected]?extension=whl&qualifier=py3-none-any
 ```
 
 #### SWID
@@ -110,7 +111,7 @@ Where the `unique-identifier` is a SWID.
 Syntax:
 
 ```text
-urn:tei:swid:<domain-name>:<swid>
+urn:tei:swid:<domain-name>:<domain-port>:<swid>
 ````
 
 Note that there is a TEI SWID type as well as a PURL SWID type.
@@ -124,12 +125,12 @@ Where the `unique-identifier` is a Hash. Supports the following hash types:
 - SHA512
 
 ```text
-urn:tei:hash:<domain-name>:<hashtype>:<hash>
+urn:tei:hash:<domain-name>:<domain-port>:<hashtype>:<hash>
 ````
 
 Example:
 ```text
-urn:tei:hash:cyclonedx.org:SHA256:fd44efd601f651c8865acf0dfeacb0df19a2b50ec69ead0262096fd2f67197b9
+urn:tei:hash:cyclonedx.org:443:SHA256:fd44efd601f651c8865acf0dfeacb0df19a2b50ec69ead0262096fd2f67197b9
 ```
 
 The origin of the hash is up to the vendor to define.
@@ -141,12 +142,12 @@ Where the `unique-identifier` is a UUID.
 Syntax:
 
 ```text
-urn:tei:uuid:<domain-name>:<uuid>
+urn:tei:uuid:<domain-name>:<domain-port>:<uuid>
 ````
 
 Example:
 ```text
-urn:tei:uuid:cyclonedx.org:d4d9f54a-abcf-11ee-ac79-1a52914d44b1
+urn:tei:uuid:cyclonedx.org:443:d4d9f54a-abcf-11ee-ac79-1a52914d44b1
 ```
 
 
@@ -169,8 +170,8 @@ product transparency exchange information.
 At the URL a well-known name space is used to find out where the API endpoint is hosted.
 This is solved by using the ".well-known" name space as defined by the IETF.
 
-- `urn:tei:uuid:products.example.com:d4d9f54a-abcf-11ee-ac79-1a52914d44b1`
-- Syntax: `urn:tei:uuid:<name based on domain>:<unique identifier>`
+- `urn:tei:uuid:products.example.com:443:d4d9f54a-abcf-11ee-ac79-1a52914d44b1`
+- Syntax: `urn:tei:uuid:<name based on domain>:<domain-port>:<unique identifier>`
 
 The name in the DNS name part points to a set of DNS records.
 
@@ -231,10 +232,10 @@ plus "/discovery?tei=", plus the TEI that is url-encoded according to [RFC3986]
 and [RFC3986]).
 
 Examples:
-1. For TEI `urn:tei:uuid:products.example.com:d4d9f54a-abcf-11ee-ac79-1a52914d44b`
-`https://api.teaexample.com/v0.2.0-beta.2/discovery?tei=urn%3Atei%3Auuid%3Aproducts.example.com%3Ad4d9f54a-abcf-11ee-ac79-1a52914d44b`
-2. For TEI `urn:tei:purl:products.example.com:pkg:deb/debian/[email protected]?arch=i386&distro=jessie`
-`https://api2.teaexample.com/mytea/v1.0.0/discovery?tei=urn%3Atei%3Apurl%3Aproducts.example.com%3Apkg%3Adeb%2Fdebian%2Fcurl%407.50.3-1%3Farch%3Di386%26distro%3Djessie`
+1. For TEI `urn:tei:uuid:products.example.com:443:d4d9f54a-abcf-11ee-ac79-1a52914d44b`
+`https://api.teaexample.com/v0.2.0-beta.2/discovery?tei=urn%3Atei%3Auuid%3Aproducts.example.com%3A443%3Ad4d9f54a-abcf-11ee-ac79-1a52914d44b`
+2. For TEI `urn:tei:purl:products.example.com:443:pkg:deb/debian/[email protected]?arch=i386&distro=jessie`
+`https://api2.teaexample.com/mytea/v1.0.0/discovery?tei=urn%3Atei%3Apurl%3Aproducts.example.com%3A443%3Apkg%3Adeb%2Fdebian%2Fcurl%407.50.3-1%3Farch%3Di386%26distro%3Djessie`
 
 The discovery endpoint is a part of the TEA OpenAPI specification. 
 
@@ -264,7 +265,7 @@ Servers MUST NOT locate the actual TEA service endpoint at the
 
 The .well-known endpoint must only be available via HTTPS. Using unencrypted HTTP is not valid.
 
-- TEI: `urn:tei:uuid:products.example.com:d4d9f54a-abcf-11ee-ac79-1a52914d44b1`
+- TEI: `urn:tei:uuid:products.example.com:443:d4d9f54a-abcf-11ee-ac79-1a52914d44b1`
 - URL: `https://products.example.com/.well-known/tea`
 
 **NOTE:** The `/.well-known/tea` names space needs to be registred.

spec/openapi.yaml

@@ -389,7 +389,7 @@ paths:
           description: Transparency Exchange Identifier (TEI) for the product being discovered. Provide the TEI as a URL-encoded string per RFC 3986, RFC 3987.
           schema:
             type: string
-            example: urn%3Atei%3Auuid%3Aproducts.example.com%3Ad4d9f54a-abcf-11ee-ac79-1a52914d44b
+            example: urn%3Atei%3Auuid%3Aproducts.example.com%3A443%3Ad4d9f54a-abcf-11ee-ac79-1a52914d44b
       responses:
         '200':
           $ref: "#/components/responses/discovery-response"