agent: user auth APIs accept and verify request capability, and add user prefix authorization API

[jgraettinger]

User authorization APIs can now escalate the capability of a signed token if the user has sufficient privilege. This can be used for administrative actions like journal splitting.

Also add a new prefix authorization API which signs an authorization token valid for a requested and authorized prefix and capability, directed at a specific data-plane.

Add a new, advanced flowctl subcommand for authorizing and printing environment variables for direct gazette access of an authorized prefix.

Workflow steps:

Use flowctl to obtain a temporary authorization to an entire (authorized) prefix:

johnny@johnny-desktop:~/estuary/flow$ flowctl --profile local raw gazctl-env --data-plane ops/dp/public/local-cluster --prefix ops.us-central1.v1/ 
2025-05-08T16:38:44.477413Z  WARN flow_client::client: authorization service tentatively rejected our request, but we'll retry before failing secs=5.692
export BROKER_ADDRESS=https://gazette.flow.localhost:8080
export BROKER_AUTH_TOKEN=(trim)
export CONSUMER_ADDRESS=https://reactor.flow.localhost:9000
export CONSUMER_AUTH_TOKEN=(trim)

Then use it with gazctl or flowctl-go corresponding Gazette PR:

johnny@johnny-desktop:~/gazette$ .build/amd64/gazctl  shards list -l ''
+--------------------------------------------------------------------------------------+---------+
|                                          ID                                          | STATUS  |
+--------------------------------------------------------------------------------------+---------+
| derivation/ops.us-central1.v1/catalog-stats-L2/1114a1376c000046/00000000-00000000    | PRIMARY |
| derivation/ops.us-central1.v1/events/L2/1114a1376c000046/00000000-00000000           | PRIMARY |
| derivation/ops.us-central1.v1/inferred-schemas/L2/1114a1376c000046/00000000-00000000 | PRIMARY |
| materialize/ops.us-central1.v1/stats-view/1114a13f78800046/00000000-00000000         | PRIMARY |
+--------------------------------------------------------------------------------------+---------+
johnny@johnny-desktop:~/gazette$ .build/amd64/gazctl  journals list -l ''
+-----------------------------------------------------------------------------------------------+
|                                             NAME                                              |
+-----------------------------------------------------------------------------------------------+
| ops.us-central1.v1/catalog-stats-L2/1114a1376c000046/pivot=00                                 |
| ops.us-central1.v1/events/L2/1114a1376c000046/event_type=connectorStatus/pivot=00             |
| ops.us-central1.v1/inferred-schemas/L2/1114a1376c000046/pivot=00                              |
| recovery/derivation/ops.us-central1.v1/catalog-stats-L2/1114a1376c000046/00000000-00000000    |
| recovery/derivation/ops.us-central1.v1/events/L2/1114a1376c000046/00000000-00000000           |
| recovery/derivation/ops.us-central1.v1/inferred-schemas/L2/1114a1376c000046/00000000-00000000 |
| recovery/materialize/ops.us-central1.v1/stats-view/1114a13f78800046/00000000-00000000         |
+-----------------------------------------------------------------------------------------------+

Example of a prefix which is not allowed at the requested capability:

johnny@johnny-desktop:~/estuary/flow$ flowctl --profile local raw gazctl-env --data-plane ops/dp/public/local-cluster --prefix ops.us-central1.v1/ --admin
2025-05-08T16:39:44.150048Z  WARN flow_client::client: authorization service tentatively rejected our request, but we'll retry before failing secs=3.523
2025-05-08T16:39:47.676877Z ERROR flow_client::client: error=POST /authorize/user/prefix: 403 Forbidden: {"status":403,"error":"johnny@foobar is not authorized to ops.us-central1.v1/ for Admin"}
Error: POST /authorize/user/prefix: 403 Forbidden: {"status":403,"error":"johnny@foobar is not authorized to ops.us-central1.v1/ for Admin"}

Documentation links affected:

(list any documentation links that you created, or existing ones that you've identified as needing updates, along with a brief description)

Notes for reviewers:

(anything that might help someone review this PR)

---

This change is 

[jshearer]

Not sure if we care about being able to guess private data-plane names, but this message+status code being different from the "not found" error below would let a potential bad actor check whether a guessed data-plane exists or not.

[jgraettinger]

We're verifying their authorization to the requested data-plane name before we check whether the name actually exists. They will always get a FORBIDDEN if they don't have RBAC access, regardless of whether it exists.