m-lab / token-exchange

70%

main: 50%

Pull #7

github

feat: implement client-integration token exchange

This diff implements token exchange for client integrations.

This is the general design we're implementing:

1. organizations maintaining client integrations (e.g., Acme Inc
embedding m-lab/ndt7-client-js to provide NDT to its users)
register with the system and obtain 1+ API keys

2. Acme Inc provisions a backend `B` that stores its API keys

3. backend `B` receives a query for Acme Inc clients when
they initiate running a NDT test

4. backend `B` queries m-lab/token-exchange to exchange one
of its API keys with a short-lived JWT

5. backend `B` returns the JWT to the client

6. the client queries m-lab/locate including the JWT

7. m-lab/locate uses the JWT to route the client to the proper
NDT server and/or to perform accounting and access control to
prevent a single integration from overloading the platform

8. the JWT is included into the URLs to access m-lab/ndt-server
where it is again used to perform access control

This diff only implements the token-exchange part of this design.

Client-integration keys use a hierarchical format that encodes both
the integration ID and key ID for O(1) datastore lookups:

```
mlabk.cii_<integrationID>.ki_<keyID>.<keySecret>
```

The hierarchical structure enables:

- O(1) lookup via parent-child datastore keys

- No duplication of IDs in entity fields

- Natural cascade deletion

Unlike autojoin tokens (which contain only `org`), client-integration
JWTs contain both integration ID and key ID:

```
{"int_id": "...", "key_id": "...", ...}
```

This allows downstream services (locate, ndt-server) to track which
specific API key was used for each test, enabling per-key metrics
and access control.

Key secrets are not stored in Datastore. We use SHA-256 hashing with
constant-time comparison to verify them against stored hashes. This
provides sufficient security given that API keys are high-entropy
machine-generated secrets, while avoiding the high CPU cost of
bcry... (continued)

224 of 303 new or added lines in 7 files covered. (73.93%)

294 of 423 relevant lines covered (69.5%)

0.78 hits per line