feat: add scoped API key guard

[edehvictor]

Closes #701
Closes #700
Closes #699
Closes #689

Summary

This contribution adds a reusable scoped API-key guard for protected backend endpoints. API keys are loaded from the API_KEYS configuration as a key-to-scopes map, compared using fixed-length timing-safe digests, and attached to the request with their granted scopes.

Changes

• Added endpoint metadata through RequireApiKeyScopes.
• Added scope enforcement with wildcard support for administrative keys.
• Added per-key request windows so one API key cannot consume another key quota.
• Added explicit unauthorized, forbidden, and rate-limit responses.
• Added focused coverage for valid keys, missing and invalid keys, insufficient scopes, per-key throttling, and scope metadata.

Configuration

Set API_KEYS to a JSON object mapping each key to its allowed scopes, for example: {"key-value":["oracle:read","claims:write"]}. Endpoints can opt into enforcement with RequireApiKeyScopes.

Testing

• Not run, per request. No install, build, test, or CI check was performed.

[drips-wave]

@edehvictor Great news! 🎉 Based on an automated assessment of this PR, the linked Wave issue(s) no longer count against your application limits.

You can now already apply to more issues while waiting for a review of this PR. Keep up the great work! 🚀

Learn more about application limits