AaaS: Add token scopes and backend IP ACL/allowlist to protect the firehose

[plansombl]

Description

The Awareness as a Service (AaaS) firehose currently has no mechanism to restrict what data a token can access or which IPs are permitted to use it. This means that if a token is leaked and not promptly revoked, it can be used by any party from any origin to access firehose data without restriction.

To mitigate this risk, two complementary controls need to be introduced:

1. Token Scopes — each token declares which data streams/resources it is permitted to access on the AaaS firehose.
2. Backend IP ACL / Allowlist — each token carries an IP allowlist; requests originating from IPs not on that list are rejected by the backend, regardless of token validity.

Together these ensure that a leaked-but-unrevoked token cannot be meaningfully exploited unless the attacker also controls a permitted IP address.

Reference

• AaaS firehose architecture (internal docs)
• Existing token issuance flow

Acceptance Criteria

• Tokens have a scopes field that limits which firehose resources/streams they may access; requests to out-of-scope resources are rejected with an appropriate error (e.g. 403 Forbidden).
• Tokens have an IP allowlist field; the backend validates the remote IP of every inbound request against this list and rejects non-matching IPs.
• Legacy token support — all currently issued tokens are treated as legacy tokens by a dedicated flag (e.g. legacy: true). Legacy tokens are automatically granted:
  • Scopes: * (wildcard — access to all resources)
  • IP allowlist: * (wildcard — any IP permitted)
  • This preserves full backwards compatibility; no existing integration breaks.
• New tokens issued after this change must have explicit scopes and an explicit IP allowlist defined at creation time (wildcards are still a valid value but must be set explicitly).
• The token issuance API/UI is updated to accept and validate scopes and ip_allowlist fields.
• Backend enforces both controls on every firehose request.
• Appropriate documentation is updated to describe the new fields and migration path for existing integrations.

Desired Output (may vary)

A hardened AaaS token model where leaked, unrevoked tokens are limited in blast radius by both scope restrictions and IP-based access control, while all existing tokens continue to function transparently as legacy */* tokens.