m-lab / token-exchange / 18950421377

70%

main: 70%

Build Type

Pull #7

github

Committed by bassosimone

Commit Message

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 focuses on token-exchange.

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.

API keys are not stored in Datastore. We use bcrypt to compare them to
the stored hashes. Integration tokens are short-lived (20s) compared
to autojoin tokens (1h).

The auth and handler layers use distinct types and methods for
autojoin vs client-integration to prevent accidental misuse at
co... (continued)

Pull Request Pull Request #7: feat: implement client-integration token exchange

Run Details

207 of 291 new or added lines in 7 files covered. (71.13%)

7 existing lines in 1 file now uncovered.

277 of 411 relevant lines covered (67.4%)

0.76 hits per line