doc: add TEA narrative drafts

api-flow/consumer.md

@@ -23,8 +23,18 @@ Component Release) to find the list of artefacts for the particular Product Rele
 ## API flow based on TEI discovery
 
 ```mermaid
-
 ---
+config:
+  sequence:
+    diagramMarginX: 60
+    diagramMarginY: 40
+    actorFontSize: 20
+    actorFontWeight: bold
+    noteFontSize: 18
+  theme: neo dark
+  layout: elk
+  look: neo
+
 title: TEA consumer flow
 ---
 sequenceDiagram
@@ -60,7 +70,6 @@ sequenceDiagram
         user ->> tea_component_release: Obtain latest collections
         tea_component_release -->> user: List of TEA Artifacts
     end
-
 ```
 
 ## API flow based on direct access to API
@@ -70,6 +79,16 @@ In this case, the client wants to search for a specific product release using th
 ```mermaid
 
 ---
+config:
+  sequence:
+    diagramMarginX: 60
+    diagramMarginY: 40
+    actorFontSize: 20
+    actorFontWeight: bold
+    noteFontSize: 18
+  theme: neo dark
+  layout: elk
+  look: neo
 title: TEA client flow with search
 ---
 
@@ -109,6 +128,16 @@ for a release.
 ```mermaid
 
 ---
+config:
+  sequence:
+    diagramMarginX: 60
+    diagramMarginY: 40
+    actorFontSize: 20
+    actorFontWeight: bold
+    noteFontSize: 18
+  theme: neo dark
+  layout: elk
+  look: neo
 title: TEA client flow with direct query for release
 ---
 
@@ -137,6 +166,16 @@ another query is done to get reason for update and new collection list of artefa
 ```mermaid
 
 ---
+config:
+  sequence:
+    diagramMarginX: 60
+    diagramMarginY: 40
+    actorFontSize: 20
+    actorFontWeight: bold
+    noteFontSize: 18
+  theme: neo
+  layout: elk
+  look: neo
 title: TEA client collection query
 ---
 

doc/authorization.md

@@ -0,0 +1,98 @@
+# Authorization
+
+The Transparency Exchange API (TEA) uses a scope-based authorization model. Permissions are granted through scopes assigned to authenticated identities. Scopes follow a hierarchical structure with read operations generally requiring fewer permissions than write operations.
+
+## Scope Model
+
+Scopes are granted to identities during authentication. Bearer tokens include scopes in the `scope` claim as a space-separated list. mTLS certificates are mapped to scopes through server configuration.
+
+### Scope Hierarchy
+
+```
+SCOPE_ADMIN_FULL (admin)
+├── SCOPE_PUBLISHER_* (publisher)
+│   ├── SCOPE_PUBLISHER_PRODUCTS_WRITE
+│   ├── SCOPE_PUBLISHER_COMPONENTS_WRITE
+│   ├── SCOPE_PUBLISHER_RELEASES_WRITE
+│   ├── SCOPE_PUBLISHER_ARTIFACTS_WRITE
+│   └── SCOPE_PUBLISHER_COLLECTIONS_WRITE
+└── SCOPE_CONSUMER_* (consumer)
+    ├── SCOPE_CONSUMER_PRODUCTS_READ
+    ├── SCOPE_CONSUMER_COMPONENTS_READ
+    ├── SCOPE_CONSUMER_COLLECTIONS_READ
+    ├── SCOPE_CONSUMER_ARTIFACTS_READ
+    ├── SCOPE_CONSUMER_ARTIFACTS_DOWNLOAD
+    └── SCOPE_CONSUMER_INSIGHTS_QUERY
+```
+
+## Consumer Scopes
+
+### Read Operations
+
+- `SCOPE_CONSUMER_PRODUCTS_READ`: List and retrieve product metadata
+- `SCOPE_CONSUMER_COMPONENTS_READ`: List and retrieve component metadata
+- `SCOPE_CONSUMER_COLLECTIONS_READ`: Access collection metadata and versions
+- `SCOPE_CONSUMER_ARTIFACTS_READ`: Retrieve artifact metadata
+- `SCOPE_CONSUMER_ARTIFACTS_DOWNLOAD`: Download artifact content
+- `SCOPE_CONSUMER_INSIGHTS_QUERY`: Execute CEL-based queries and searches
+
+## Publisher Scopes
+
+### Write Operations
+
+- `SCOPE_PUBLISHER_PRODUCTS_WRITE`: Create, update, delete products
+- `SCOPE_PUBLISHER_COMPONENTS_WRITE`: Create, update, delete components
+- `SCOPE_PUBLISHER_RELEASES_WRITE`: Create, update product/component releases
+- `SCOPE_PUBLISHER_ARTIFACTS_WRITE`: Upload and delete artifacts
+- `SCOPE_PUBLISHER_COLLECTIONS_WRITE`: Create and update collections
+
+## Admin Scopes
+
+### Administrative Operations
+
+- `SCOPE_ADMIN_FULL`: Full administrative access including user management, system configuration, and audit functions
+
+## Authorization Logic
+
+### API Endpoint Requirements
+
+| Endpoint                      | Required Scopes                     |
+| ----------------------------- | ----------------------------------- |
+| `GET /.well-known/tea`        | None (public)                       |
+| `GET /v1/discovery`           | None (public)                       |
+| `GET /v1/products*`           | `SCOPE_CONSUMER_PRODUCTS_READ`      |
+| `GET /v1/components*`         | `SCOPE_CONSUMER_COMPONENTS_READ`    |
+| `GET /v1/collections*`        | `SCOPE_CONSUMER_COLLECTIONS_READ`   |
+| `GET /v1/artifacts*`          | `SCOPE_CONSUMER_ARTIFACTS_READ`     |
+| `GET /v1/artifacts/*/content` | `SCOPE_CONSUMER_ARTIFACTS_DOWNLOAD` |
+| `POST /v1/insights/*`         | `SCOPE_CONSUMER_INSIGHTS_QUERY`     |
+| `POST /v1/publisher/*`        | Publisher scopes as above           |
+
+### Scope Validation
+
+Servers MUST validate that the authenticated identity possesses all required scopes for the requested operation. Missing scopes result in `403 Forbidden` responses.
+
+### Scope Granularity
+
+Scopes are intentionally coarse-grained to simplify implementation. Fine-grained access control (e.g., per-object permissions) is not supported in the base specification but may be implemented as extensions.
+
+## Authorization Flow
+
+```mermaid
+flowchart TD
+    A[Request] --> B[Authenticate]
+    B --> C{Valid Identity?}
+    C -->|No| D[401 Unauthorized]
+    C -->|Yes| E[Extract Scopes]
+    E --> F{Required Scopes?}
+    F -->|No| G[403 Forbidden]
+    F -->|Yes| H[Process Request]
+    H --> I[Response]
+```
+
+## Security Considerations
+
+- Implement least privilege: grant only necessary scopes
+- Regularly rotate credentials and review scope assignments
+- Audit authorization decisions for compliance
+- Consider scope expiration for temporary access

doc/tea-requirements.md

@@ -1,6 +1,7 @@
 # TEA Requirements
 
 ## Repository discovery
+
 Based on an identifier a repository URL needs to be found. The identifier can be:
 
 - PURL
@@ -34,6 +35,9 @@ Collections are OPTIONAL.
 - VDR - Vulnerability Disclosure Report
 - VEX - Vulnerability Exploitability eXchange
 - CDXA - Attestation
+- ML-BOM - Machine Learning Bill of Material (profile of SBOM)
+- DATA-BOM - Data Bill of Material (profile of SBOM)
+- AI-BOM - Artificial Intelligence Bill of Material (profile of SBOM)
 
 Authn/Authz MUST be supported
 
@@ -61,7 +65,7 @@ Authn/Authz MUST be supported
 
 ## Artefact Publishing
 
-The API MUST provide a way to publish an artefact, either standalone or to a collection. 
+The API MUST provide a way to publish an artefact, either standalone or to a collection.
 The detection of duplicate artefacts with the same identity MUST be handled and prevented.
 Authn/Authz MUST be supported
 
@@ -85,11 +89,11 @@ PURL, CPE, SWID, GAV, GTIN, and GMN.
 
 For example:
 
-- Return the identity of all BOMs that have a vulnerable version of Apache Log4J: 
+- Return the identity of all BOMs that have a vulnerable version of Apache Log4J:
   `pkg:maven/org.apache.logging.log4j/log4j-core@2.10.0`
 
-The API MUST provide a way to search for the metadata component across all available BOMs. 
-The API SHOULD support multiple identity formats including PURL, CPE, SWID, GAV, GTIN, and GMN. 
+The API MUST provide a way to search for the metadata component across all available BOMs.
+The API SHOULD support multiple identity formats including PURL, CPE, SWID, GAV, GTIN, and GMN.
 For example:
 
 - Return the identity of all artefacts that describe `cpe:/a:acme:commerce_suite:1.0`.

doc/tea-usecases.md

@@ -6,10 +6,10 @@ a..."
 
 The use cases are divided in two categories:
 
-* Use cases for __customers__ (end-users, manufacturers) to find a repository with 
+* Use cases for __customers__ (end-users, manufacturers) to find a repository with
   Transparency artefacts for a single unit purchased
 * Use cases where there are different __products__
-  * This applies after discovery where we need to handle various things a customer may 
+  * This applies after discovery where we need to handle various things a customer may
     buy as a single unit
 
 ## Customer focused use cases
@@ -18,18 +18,17 @@ The use cases are divided in two categories:
 
 As a consumer that has an SBOM for a product, I want to be able to retrieve VEX and VDR files automatically both for current and old versions of the software. In the SBOM the product is identified by a PURL or other means (CPE, …)
 
-
 ### C2: Consumer: Automation based on product name/identifier
 
 As a consumer, I want to download artefacts for a product based on known data.
 A combination of manufacturer, product name, vendor product ID, EAN bar code or other unique identifier.
-After discovering the base repository URL I want to be able to find a specific 
+After discovering the base repository URL I want to be able to find a specific
 product variant and version.
 
 If the consumer is a business, then the procurement process may include delivery of an SBOM with proper identifiers and possibly URLs or identifiers in another document, which may bootstrap the discovery process in a more exact way than in the case of buying a product in a retail market.
 Alice bought a gadget at the gadget store that contains a full Linux system. Where and how will she find the SBOM and VEX for the gadget?
 
-### C3: Consumer: Artefact retrieval 
+### C3: Consumer: Artefact retrieval
 
 As a consumer, I want to retrieve one or more supply chain artefacts for the products that I have access to, possibly through licensing or other means. As a consumer, I should be able to retrieve all source artefacts such as xBOMs, VDR/VEX, CDXA, and CLE.
 
@@ -42,8 +41,8 @@ A CLE captures all lifecycle events over time, however, there is a need to retri
 
 As a consumer, I want the ability to simply ask the API questions rather than having to download,
 process, and analyze raw supply chain artefacts on my own systems. Common questions should be
-provided by the API by default along with the ability to query for more complex answers using 
-the Common Expression Language (CEL). 
+provided by the API by default along with the ability to query for more complex answers using
+the Common Expression Language (CEL).
 
 _NOTE_: Project Hyades (Dependency-Track v5) already implements CEL with the CycloneDX object model and has proven that this approach works for complex queries.
 
@@ -82,7 +81,6 @@ They need to make an assessment before starting tests and possible production us
 The can either use the Debian package, the Alpine Linux Package or build a binary themselves from source code.
 How can they find the transparency exchange data sets?
 
-
 ### O1: Open Source project
 
 The hatturl open source project publish a library and a server side software on Github. This is