feat(athena): Auth module

[bkioshn]

Description

The Athena auth module replicates the authentication and authorization behavior of cat-gateway.

Auth Levels:

• AuthLevel::Required - Full validation is mandatory
• AuthLevel::Optional - Token is validated if present; skipped if absent
• AuthLevel::None - No validation performed

Reference Documentation:
For complete implementation details and specifications, refer to the Catalyst Standards Documentation.

Related Issue(s)

Closes https://github.com/input-output-hk/catalyst-internal-docs/issues/326

Notes

• src/database and src/rbac are redundant to what is in rbac-registration module, this should be moved to share in the later PR. No need to review these files
• api_key.rs , token.rs, validation.rs are extracted from cat-gateway and slightly modified to make it work in Athena.
• The main implementation is in the lib.rs
• Open-api spec is not yet done

Tests

The test is made by running the whole Athena app using just build-run-all

The bearer token is generated using functionality in https://github.com/input-output-hk/catalyst-voices/tree/main/catalyst-gateway/tests/api_tests/integration

There is a hardcode information (cat id, signing key etc) that is used to create the Auth token. The hardcode cat id is a valid registration and exist in Cardano preprod

Please note that if this token is used to test again, it will be invalid due to expired nonce.

Success 200

curl -v -X GET \
  -H "Host: app.hermes.local" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer catid.:[email protected]/0KGVpkXVe5-h1RfIb08Mnc-xMZTzSX5VVnPDaHvhrqQ.aYCoRyWc-8fxtnBTvFxmVzNLUCT3d5ebHe6ZrLvO2xaPRmkwqQLY5BU51uQulfHqj3Zdr8DlMALcpyP9UwltBQ" \
  "http://localhost:5000/api/v1/registration?lookup=preprod.cardano/-oJaY9wntIVvpNzJivGmWJHTZahFSfGZNSFM1bnBHG4"
Note: Unnecessary use of -X or --request, GET is already inferred.
* Host localhost:5000 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying [::1]:5000...
* connect to ::1 port 5000 from ::1 port 34122 failed: Connection refused
*   Trying 127.0.0.1:5000...
* Connected to localhost (127.0.0.1) port 5000
> GET /api/v1/registration?lookup=preprod.cardano/-oJaY9wntIVvpNzJivGmWJHTZahFSfGZNSFM1bnBHG4 HTTP/1.1
> Host: app.hermes.local
> User-Agent: curl/8.5.0
> Accept: */*
> Content-Type: application/json
> Authorization: Bearer catid.:[email protected]/0KGVpkXVe5-h1RfIb08Mnc-xMZTzSX5VVnPDaHvhrqQ.aYCoRyWc-8fxtnBTvFxmVzNLUCT3d5ebHe6ZrLvO2xaPRmkwqQLY5BU51uQulfHqj3Zdr8DlMALcpyP9UwltBQ
> 
< HTTP/1.1 200 OK
< content-type: application/json
< content-length: 1112
< date: Fri, 24 Oct 2025 07:10:49 GMT
< 
{"catalyst_id":"preprod.cardano/-oJaY9wntIVvpNzJivGmWJHTZahFSfGZNSFM1bnBHG4","last_persistent_txn":"0xd8a21ec3e89e6f38abad03cbff284e6e353fe6e8f56d8648712caf0c60579ce8","purpose":["ca7a1457-ef9f-4c7f-9c74-7f8c4a4cfa6c"],"roles":{"0":{"signing_keys":[{"is_persistent":true,"time":"2025-09-15T14:34:16+00:00","key_type":"x509","key_value":"0x308201173081caa00302010202045b2a4d4d300506032b657030003022180f32303235303931353134333335335a180f39393939313233313233353935395a3000302a300506032b6570032100fa825a63dc27b4856fa4dcc98af1a65891d365a84549f19935214cd5b9c11c6ea3623060305e0603551d110457305586537765622b63617264616e6f3a2f2f616464722f7374616b655f746573743175726a657437656c366c6e633466723866776c7136713432713574756830386770386a353772396a723370776d337172676a703866300506032b6570034100105397cb1da9a7af96a767d552045fde67748516d2ca529b2ab0f8fb4c0275d5b35db3455297509a3c31cea1b6ae2b3d982523f143d6065716e3614aaeb0cd0b"}],"payment_addresses":[{"is_persistent":true,"time":"2025-09-15T14:34:16+00:00","address":"addr_test1qr5c7ap3ty70c30v* Connection #0 to host localhost left intact
j5wfjqhwrq6c46nwlca295et02wvpe89jhanl4l832jxwja7p5p25pghew7wsz09fuxty8zzahzql5x5jf"}]}}}%     

Invalid signature 403

curl -v -X GET \
  -H "Host: app.hermes.local" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer catid.:[email protected]/0KGVpkXVe5-h1RfIb08Mnc-xMZTzSX5VVnPDaHvhrqQ.YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYQ" \
  "http://localhost:5000/api/v1/registration?lookup=preprod.cardano/-oJaY9wntIVvpNzJivGmWJHTZahFSfGZNSFM1bnBHG4"
# Expected: 403 Forbidden
Note: Unnecessary use of -X or --request, GET is already inferred.
* Host localhost:5000 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying [::1]:5000...
* connect to ::1 port 5000 from ::1 port 45226 failed: Connection refused
*   Trying 127.0.0.1:5000...
* Connected to localhost (127.0.0.1) port 5000
> GET /api/v1/registration?lookup=preprod.cardano/-oJaY9wntIVvpNzJivGmWJHTZahFSfGZNSFM1bnBHG4 HTTP/1.1
> Host: app.hermes.local
> User-Agent: curl/8.5.0
> Accept: */*
> Content-Type: application/json
> Authorization: Bearer catid.:[email protected]/0KGVpkXVe5-h1RfIb08Mnc-xMZTzSX5VVnPDaHvhrqQ.YWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYWFhYQ
> 
< HTTP/1.1 403 Forbidden
< content-type: application/json
< content-length: 88
< date: Fri, 24 Oct 2025 07:10:30 GMT
< 
* Connection #0 to host localhost left intact
{"Forbidden":"Insufficient Permission for Catalyst RBAC Token: [\"INVALID SIGNATURE\"]"}%    

Wrong format 401

curl -v -X GET \
  -H "Host: app.hermes.local" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer catid.id.catalyst://:[email protected]/0KGVpkXVe5-h1RfIb08Mnc-xMZTzSX5VVnPDaHvhrqQ.jqVYU2Yq24XDpLyKjCwqL3CBLhLy9ntgFNN_lEYjvyC-BpXeNoDp-0d7k7rU8kNhGcYCo4qx1Gj9YtAl3hlWBA" \
  "http://localhost:5000/api/v1/registration?lookup=preprod.cardano/-oJaY9wntIVvpNzJivGmWJHTZahFSfGZNSFM1bnBHG4"
# Expected: 401 Unauthorized
Note: Unnecessary use of -X or --request, GET is already inferred.
* Host localhost:5000 was resolved.
* IPv6: ::1
* IPv4: 127.0.0.1
*   Trying [::1]:5000...
* connect to ::1 port 5000 from ::1 port 47188 failed: Connection refused
*   Trying 127.0.0.1:5000...
* Connected to localhost (127.0.0.1) port 5000
> GET /api/v1/registration?lookup=preprod.cardano/-oJaY9wntIVvpNzJivGmWJHTZahFSfGZNSFM1bnBHG4 HTTP/1.1
> Host: app.hermes.local
> User-Agent: curl/8.5.0
> Accept: */*
> Content-Type: application/json
> Authorization: Bearer catid.id.catalyst://:[email protected]/0KGVpkXVe5-h1RfIb08Mnc-xMZTzSX5VVnPDaHvhrqQ.jqVYU2Yq24XDpLyKjCwqL3CBLhLy9ntgFNN_lEYjvyC-BpXeNoDp-0d7k7rU8kNhGcYCo4qx1Gj9YtAl3hlWBA
> 
< HTTP/1.1 401 Unauthorized
< content-type: application/json
< content-length: 92
< date: Fri, 24 Oct 2025 07:07:04 GMT
< 
* Connection #0 to host localhost left intact
{"Unauthorized":"Fail to parse RBAC token string, err: Catalyst ID must be in an ID format"}%  

Please confirm the following checks

• My code follows the style guidelines of this project
• I have performed a self-review of my code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published in downstream module

[cong-or]

lgtm