feat: well-known discovery via static json response

taleodor · taleodor · commit 332f5aa7ecc9 · 2025-10-03T19:51:07.000-04:00
This commit:

1. Converts ./well-known/tea endpoint to a static json object with defined schema
2. Provides rules for discovery based on TEI and static well-known endpoint (see p.1)
3. Adds error type to 404 responses, which can be OBJECT_UNKNOWN or OBJECT_NOT_SHAREABLE

Signed-off-by: Pavel Shukhman &lt;taleodor@gmail.com&gt;
diff --git a/discovery/readme.md b/discovery/readme.md
@@ -180,20 +180,65 @@ These point to the hosts available for the Transparency Exchange API.
 The TEA client connects to the host using HTTPS and validates the certificate.
 The URI is composed of the name with the `/.well-known/tea` prefix added.
 
-This results in the base URI (without the product identifier) 
-`https://tea.example.com/.well-known/tea/` 
+This results in the base URI 
+`https://tea.example.com/.well-known/tea`
+
+This URI must contain static json that lists the available TEA server endpoints and supported versions.
+The json must conform to the [TEA Well-Known Schema](tea-well-known.schema.json).
+
+Example:
+```json
+{
+  "endpoints": [
+    {
+      "url": "https://api.teaexample.com",
+      "versions": 
+        [
+          "0.1.0-beta.1",
+          "0.2.0-beta.2",
+          "1.0"
+        ]
+    },
+    {
+      "url": "https://api2.teaexample.com/mytea",
+      "versions": 
+        [
+          "1.0"
+        ]
+    }
+  ]
+}
+```
 
 
 ## Connecting to the API
 
-When connecting to the `.well-known/tea` URI with the unique identifier
-a HTTP redirect is **required**.
+Clients must pick any one of the endpoints listed in the `.well-known/tea` json
+response. They must then construct the full URL to the API by appending the
+"/v" plus one of the versions listed in the `versions` array of the selected endpoint,
+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/curl@7.50.3-1?arch=i386&distro=jessie`
+`https://api2.teaexample.com/mytea/v1.0/discovery?tei=urn%3Atei%3Apurl%3Aproducts.example.com%3Apkg%3Adeb%2Fdebian%2Fcurl%407.50.3-1%3Farch%3Di386%26distro%3Djessie`
+
+The discovery endpoint is a part of the TEA OpenAPI specification. 
+
+If the TEI is known to the TEA server, the discovery endpoint must return at least 
+the product release uuid, the root URL of the TEA server, the list of supported
+versions, plus the response may have other fields based on the current version of 
+the TEA OpenAPI specification.
+
+If the TEI is not known to the TEA server, the discovery endpoint must return a 404 
+status code with a response describing the error.
+
+TODO: Handle Auth errors (401, 403) and corresponding messages.
 
-The server MUST redirect HTTP requests for that resource
-to the actual "context path" using one of the available mechanisms
-provided by HTTP (e.g., using a 301, 303, or 307 response).  Clients
-MUST handle HTTP redirects on the `.well-known` URI.  Servers MUST
-NOT locate the actual TEA service endpoint at the
+## Notes Regarding .well-known
+Servers MUST NOT locate the actual TEA service endpoint at the
 `.well-known` URI as per Section 1.1 of [RFC5785].
 
 ### Overview: Finding the Index using DNS result
@@ -203,7 +248,7 @@ Append the product part of the TEI to the URI found
 - TEI: `urn:tei:uuid:products.example.com:d4d9f54a-abcf-11ee-ac79-1a52914d44b1`
 - DNS record: `products.example.com`
 - URL: `https://products.example.com/.well-known/tea/d4d9f54a-abcf-11ee-ac79-1a52914d44b1/`
-- HTTP 302 redirect to "https://teapot02.consumer.example.com/tea/v2/product/d4d9f54a-abcf-11ee-ac79-1a52914d44b1'
+- HTTP 302 redirect to `https://teapot02.consumer.example.com/tea/v2/product/d4d9f54a-abcf-11ee-ac79-1a52914d44b1`
 
 Always prefix with the https:// scheme. http (unencrypted) is not valid.
 
diff --git a/discovery/tea-well-known.schema.json b/discovery/tea-well-known.schema.json
@@ -0,0 +1,61 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://cyclonedx.github.io/transparency-exchange-api/discovery/tea-well-known.schema.json",
+  "title": "TEA .well-known discovery document",
+  "description": "JSON Schema for the TEA .well-known/tea discovery payload that lists available TEA API endpoints and supported versions.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["endpoints"],
+  "properties": {
+    "endpoints": {
+      "type": "array",
+      "description": "List of available TEA service endpoints and their supported versions.",
+      "minItems": 1,
+      "items": { "$ref": "#/definitions/endpoint" }
+    }
+  },
+  "definitions": {
+    "endpoint": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["url", "versions"],
+      "properties": {
+        "url": {
+          "type": "string",
+          "format": "uri",
+          "description": "Base URL of the TEA API endpoint (no trailing slash)."
+        },
+        "versions": {
+          "type": "array",
+          "description": "Supported TEA API versions for this endpoint. Use with the /v{version} prefix when constructing requests.",
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "pattern": "^\\d+\\.\\d+(?:\\.\\d+)?(?:-[0-9A-Za-z.-]+)?$",
+            "examples": [
+              "0.1.0-beta.1",
+              "0.2.0-beta.2",
+              "1.0.0",
+              "1.0"
+            ],
+            "description": "TEA OpenAPI Spec Version identifier, conforms to SemVer 2.0 (https://semver.org/)."
+          }
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "endpoints": [
+        {
+          "url": "https://api.teaexample.com",
+          "versions": ["0.1.0-beta.1", "0.2.0-beta.2", "1.0"]
+        },
+        {
+          "url": "https://api2.teaexample.com/mytea",
+          "versions": ["1.0"]
+        }
+      ]
+    }
+  ]
+}
diff --git a/spec/openapi.yaml b/spec/openapi.yaml
@@ -378,6 +378,53 @@ paths:
           $ref: "#/components/responses/404-object-by-id-not-found"
       tags:
         - TEA Artifact
+  /discovery:
+    get:
+      description: Discovery endpoint which resolves TEI into product release UUID.
+      operationId: discoveryByTei
+      parameters:
+        - name: tei
+          in: query
+          required: true
+          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
+      responses:
+        '200':
+          description: Discovery information for the requested TEI
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: false
+                properties:
+                  productReleaseUuid:
+                    description: UUID of the resolved TEA Product Release
+                    $ref: "#/components/schemas/uuid"
+                    example: d4d9f54a-abcf-11ee-ac79-1a52914d44b
+                  rootUrl:
+                    description: Root URL of the TEA server for this TEI without trailing slash
+                    type: string
+                    format: uri
+                    example: https://api.teaexample.com
+                  versions:
+                    description: Supported TEA API versions at this server without v prefix
+                    type: array
+                    minItems: 1
+                    items:
+                      type: string
+                    example: ["0.2.0-beta.2", "1.0"]
+                required:
+                  - productReleaseUuid
+                  - rootUrl
+                  - versions
+        '400':
+          $ref: "#/components/responses/400-invalid-request"
+        '404':
+          $ref: "#/components/responses/404-object-by-id-not-found"
+      tags:
+        - TEA Discovery
 components:
   schemas:
     #
@@ -974,6 +1021,12 @@ components:
         - BLAKE2b-384
         - BLAKE2b-512
         - BLAKE3
+    unknown-error-type:
+      type: string
+      description: Classification of TEA error response
+      enum:
+        - OBJECT_UNKNOWN
+        - OBJECT_NOT_SHAREABLE
     #
     # Types used in API responses
     #
@@ -1039,14 +1092,16 @@ components:
         application/json: {}
     404-object-by-id-not-found:
       description: Object requested by identifier not found
-      content:
-        application/json: {}
-    paginated-product:
-      description: A paginated response containing TEA Products
       content:
         application/json:
           schema:
-            $ref: "#/components/schemas/paginated-product-response"
+            type: object
+            additionalProperties: false
+            properties:
+              error:
+                $ref: "#/components/schemas/unknown-error-type"
+            required:
+              - error
     paginated-product-release:
       description: A paginated response containing TEA Product Releases
       content:
@@ -1128,6 +1183,7 @@ tags:
   - name: TEA Component
   - name: TEA Component Release
   - name: TEA Artifact
+  - name: TEA Discovery
 externalDocs:
   description: Transparency Exchange API specification
   url: https://github.com/CycloneDX/transparency-exchange-api
