Skip to content

Commit 48dec1c

Browse files
author
Mohamed Chorfa
committed
spec: add TEA discovery, proto, and schema drafts
1 parent 8b33377 commit 48dec1c

44 files changed

Lines changed: 9969 additions & 14 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎api-flow/consumer.md‎

Lines changed: 41 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -23,8 +23,18 @@ Component Release) to find the list of artefacts for the particular Product Rele
2323
## API flow based on TEI discovery
2424

2525
```mermaid
26-
2726
---
27+
config:
28+
sequence:
29+
diagramMarginX: 60
30+
diagramMarginY: 40
31+
actorFontSize: 20
32+
actorFontWeight: bold
33+
noteFontSize: 18
34+
theme: neo dark
35+
layout: elk
36+
look: neo
37+
2838
title: TEA consumer flow
2939
---
3040
sequenceDiagram
@@ -60,7 +70,6 @@ sequenceDiagram
6070
user ->> tea_component_release: Obtain latest collections
6171
tea_component_release -->> user: List of TEA Artifacts
6272
end
63-
6473
```
6574

6675
## 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
7079
```mermaid
7180
7281
---
82+
config:
83+
sequence:
84+
diagramMarginX: 60
85+
diagramMarginY: 40
86+
actorFontSize: 20
87+
actorFontWeight: bold
88+
noteFontSize: 18
89+
theme: neo dark
90+
layout: elk
91+
look: neo
7392
title: TEA client flow with search
7493
---
7594
@@ -109,6 +128,16 @@ for a release.
109128
```mermaid
110129
111130
---
131+
config:
132+
sequence:
133+
diagramMarginX: 60
134+
diagramMarginY: 40
135+
actorFontSize: 20
136+
actorFontWeight: bold
137+
noteFontSize: 18
138+
theme: neo dark
139+
layout: elk
140+
look: neo
112141
title: TEA client flow with direct query for release
113142
---
114143
@@ -137,6 +166,16 @@ another query is done to get reason for update and new collection list of artefa
137166
```mermaid
138167
139168
---
169+
config:
170+
sequence:
171+
diagramMarginX: 60
172+
diagramMarginY: 40
173+
actorFontSize: 20
174+
actorFontWeight: bold
175+
noteFontSize: 18
176+
theme: neo
177+
layout: elk
178+
look: neo
140179
title: TEA client collection query
141180
---
142181

‎doc/authentication.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Authentication
2+
3+
The Transparency Exchange API (TEA) supports two primary authentication mechanisms: Bearer Token authentication and Mutual TLS (mTLS) authentication. Implementations MUST support at least one of these mechanisms, and SHOULD support both for maximum compatibility.
4+
5+
## Bearer Token Authentication
6+
7+
Bearer token authentication uses JSON Web Tokens (JWTs) issued by an external identity provider. This is the recommended authentication mechanism for most use cases.
8+
9+
### Token Acquisition
10+
11+
Tokens are acquired out-of-band from the TEA server. The exact process depends on the service provider's identity management system, but typically involves:
12+
13+
1. User or service authenticates with the provider's portal or API
14+
2. Provider issues a short-lived JWT (recommended: < 1 hour)
15+
3. Client includes the token in API requests
16+
17+
### Token Format
18+
19+
Tokens MUST be valid JWTs conforming to RFC 7519. The token payload SHOULD include:
20+
21+
- `iss`: Issuer identifier
22+
- `sub`: Subject (user or service identifier)
23+
- `aud`: Audience (TEA server identifier)
24+
- `exp`: Expiration time
25+
- `iat`: Issued at time
26+
- `scope`: Space-separated list of authorized scopes
27+
28+
### Request Format
29+
30+
Include the token in the `Authorization` header:
31+
32+
```
33+
Authorization: Bearer <token>
34+
```
35+
36+
### Token Validation
37+
38+
Servers MUST validate:
39+
40+
- Token signature using the issuer's public key
41+
- Token expiration (`exp` claim)
42+
- Token audience (`aud` claim)
43+
- Required scopes for the operation
44+
45+
## Mutual TLS Authentication
46+
47+
Mutual TLS authentication uses client certificates for mutual authentication between client and server.
48+
49+
### Certificate Requirements
50+
51+
- Client certificates MUST use ECDSA P-384 or Ed25519 algorithms
52+
- Certificates MUST be issued by a trusted Certificate Authority (CA)
53+
- Certificate Subject Alternative Name (SAN) MUST include the client identifier
54+
55+
### TLS Configuration
56+
57+
- Minimum TLS version: 1.3
58+
- Server MUST request client certificates
59+
- Server MUST validate certificate chain
60+
- Client MUST present valid certificate
61+
62+
### Authorization Mapping
63+
64+
The client certificate's subject or SAN is mapped to TEA identities and scopes through server-side configuration.
65+
66+
## Authentication Flow
67+
68+
```mermaid
69+
sequenceDiagram
70+
participant Client
71+
participant TEA Server
72+
participant IdP
73+
74+
alt Bearer Token
75+
Client->>IdP: Acquire token
76+
IdP-->>Client: JWT token
77+
Client->>TEA Server: Request + Authorization: Bearer <token>
78+
TEA Server->>TEA Server: Validate token
79+
else mTLS
80+
Client->>TEA Server: TLS handshake with client cert
81+
TEA Server->>TEA Server: Validate certificate
82+
end
83+
84+
TEA Server-->>Client: Authenticated response
85+
```
86+
87+
## Error Responses
88+
89+
- `401 Unauthorized`: Missing or invalid credentials
90+
- `403 Forbidden`: Valid credentials but insufficient permissions
91+
92+
## Security Considerations
93+
94+
- Tokens SHOULD be short-lived (< 1 hour)
95+
- mTLS certificates SHOULD have short validity periods
96+
- Implement token revocation mechanisms
97+
- Log authentication failures for security monitoring

‎doc/authorization.md‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
# Authorization
2+
3+
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.
4+
5+
## Scope Model
6+
7+
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.
8+
9+
### Scope Hierarchy
10+
11+
```
12+
SCOPE_ADMIN_FULL (admin)
13+
├── SCOPE_PUBLISHER_* (publisher)
14+
│ ├── SCOPE_PUBLISHER_PRODUCTS_WRITE
15+
│ ├── SCOPE_PUBLISHER_COMPONENTS_WRITE
16+
│ ├── SCOPE_PUBLISHER_RELEASES_WRITE
17+
│ ├── SCOPE_PUBLISHER_ARTIFACTS_WRITE
18+
│ └── SCOPE_PUBLISHER_COLLECTIONS_WRITE
19+
└── SCOPE_CONSUMER_* (consumer)
20+
├── SCOPE_CONSUMER_PRODUCTS_READ
21+
├── SCOPE_CONSUMER_COMPONENTS_READ
22+
├── SCOPE_CONSUMER_COLLECTIONS_READ
23+
├── SCOPE_CONSUMER_ARTIFACTS_READ
24+
├── SCOPE_CONSUMER_ARTIFACTS_DOWNLOAD
25+
└── SCOPE_CONSUMER_INSIGHTS_QUERY
26+
```
27+
28+
## Consumer Scopes
29+
30+
### Read Operations
31+
32+
- `SCOPE_CONSUMER_PRODUCTS_READ`: List and retrieve product metadata
33+
- `SCOPE_CONSUMER_COMPONENTS_READ`: List and retrieve component metadata
34+
- `SCOPE_CONSUMER_COLLECTIONS_READ`: Access collection metadata and versions
35+
- `SCOPE_CONSUMER_ARTIFACTS_READ`: Retrieve artifact metadata
36+
- `SCOPE_CONSUMER_ARTIFACTS_DOWNLOAD`: Download artifact content
37+
- `SCOPE_CONSUMER_INSIGHTS_QUERY`: Execute CEL-based queries and searches
38+
39+
## Publisher Scopes
40+
41+
### Write Operations
42+
43+
- `SCOPE_PUBLISHER_PRODUCTS_WRITE`: Create, update, delete products
44+
- `SCOPE_PUBLISHER_COMPONENTS_WRITE`: Create, update, delete components
45+
- `SCOPE_PUBLISHER_RELEASES_WRITE`: Create, update product/component releases
46+
- `SCOPE_PUBLISHER_ARTIFACTS_WRITE`: Upload and delete artifacts
47+
- `SCOPE_PUBLISHER_COLLECTIONS_WRITE`: Create and update collections
48+
49+
## Admin Scopes
50+
51+
### Administrative Operations
52+
53+
- `SCOPE_ADMIN_FULL`: Full administrative access including user management, system configuration, and audit functions
54+
55+
## Authorization Logic
56+
57+
### API Endpoint Requirements
58+
59+
| Endpoint | Required Scopes |
60+
| ----------------------------- | ----------------------------------- |
61+
| `GET /.well-known/tea` | None (public) |
62+
| `GET /v1/discovery` | None (public) |
63+
| `GET /v1/products*` | `SCOPE_CONSUMER_PRODUCTS_READ` |
64+
| `GET /v1/components*` | `SCOPE_CONSUMER_COMPONENTS_READ` |
65+
| `GET /v1/collections*` | `SCOPE_CONSUMER_COLLECTIONS_READ` |
66+
| `GET /v1/artifacts*` | `SCOPE_CONSUMER_ARTIFACTS_READ` |
67+
| `GET /v1/artifacts/*/content` | `SCOPE_CONSUMER_ARTIFACTS_DOWNLOAD` |
68+
| `POST /v1/insights/*` | `SCOPE_CONSUMER_INSIGHTS_QUERY` |
69+
| `POST /v1/publisher/*` | Publisher scopes as above |
70+
71+
### Scope Validation
72+
73+
Servers MUST validate that the authenticated identity possesses all required scopes for the requested operation. Missing scopes result in `403 Forbidden` responses.
74+
75+
### Scope Granularity
76+
77+
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.
78+
79+
## Authorization Flow
80+
81+
```mermaid
82+
flowchart TD
83+
A[Request] --> B[Authenticate]
84+
B --> C{Valid Identity?}
85+
C -->|No| D[401 Unauthorized]
86+
C -->|Yes| E[Extract Scopes]
87+
E --> F{Required Scopes?}
88+
F -->|No| G[403 Forbidden]
89+
F -->|Yes| H[Process Request]
90+
H --> I[Response]
91+
```
92+
93+
## Security Considerations
94+
95+
- Implement least privilege: grant only necessary scopes
96+
- Regularly rotate credentials and review scope assignments
97+
- Audit authorization decisions for compliance
98+
- Consider scope expiration for temporary access

0 commit comments

Comments
 (0)