story: Add `filter.fga_role` Query Parameter for FGA-Based Pre-filtering

[FWuermse]

User Story

As a portal user,
I want to filter search results by my FGA role (e.g. filter.fga_role=owner)
so that I only see resources belonging to accounts I own, without having to manually identify which accounts those are.

Context

Currently there is no way to say "only show me resources I own" in a single request. Users who are owners of a subset of accounts see every resource in OpenSearch, with post-hoc FGA filtering silently trimming results. This limits queries for the users role dependencies.

Solution Path

Add filter.fga_role=<relation> as a new recognized query parameter distinct from the generic filter.<field> family. When present, it is resolved at query time and before the OpenSearch request is issued. We can do this by fetching the set of FGA objects for which the user holds the requested relation, then injecting those as an OpenSearch terms filter on filterable_fields.account_fga_object (or a similar field mapping).

Example:

GET /rest/v1/search?q=my-app&filter.fga_role=owner

Returns only resources belonging to accounts where the authenticated user has the owner relation in OpenFGA.

Out of Scope

• Changing the post-query FGA BatchCheck behavior.
• Exposing filter.fga_role on the /resources endpoint.
• Multi-value filter.fga_role (single relation only for this ticket).

---

Open Question

Should filter.fga_role be validated against a known set of relations (e.g. owner, viewer, editor) or left open to any string?

Acceptance Criteria

• GET /rest/v1/search?filter.fga_role=owner returns only resources where the authenticated user holds the owner relation in OpenFGA for the associated account.
• GET /rest/v1/search?filter.fga_role=viewer likewise scopes to viewer-accessible resources.
• Combining filter.fga_role with other filter.* params works correctly (AND semantics).
• If the user holds the requested role on zero accounts, the response is an empty result set (no scan, fast return).
• filter.fga_role with an unrecognized/invalid relation value returns HTTP 400.
• The existing post-query FGA BatchCheck still runs as a safety net — filter.fga_role is an optimization, not a security bypass.
• Unit tests cover: role resolved to a non-empty list, role resolved to empty list, invalid relation, combined with other filters.
• No change to existing behavior when filter.fga_role is absent.

Parent Epic

No response

Additional Context

No response