feat: Add authorization context helpers and server-side filtering for timeseries

[vairav]

Summary

Add authorization infrastructure to support fine-grained access control for timeseries data:

• Create AuthorizationContextHelper to parse x-cwms-auth-context header and extract user context (username, offices, roles, persona)
• Create AuthorizationFilterHelper to generate JOOQ conditions for server-side filtering (embargo rules, time windows, office restrictions, data classification)
• Integrate authorization filtering in TimeSeriesController with office access validation
• Apply embargo and time window filters at DAO level in TimeSeriesDaoImpl using JOOQ conditions
• All filtering happens at database level - no unauthorized data ever leaves the database

This implementation supports the authorization proxy pattern where policy decisions are made by OPA and enforcement happens in the CWMS Data API via the authorization context header.

---

Screenshots

N/A - Backend authorization infrastructure

---

Todos

• AuthorizationContextHelper for header parsing
• AuthorizationFilterHelper for JOOQ filter generation
• Office-based filtering (allowed_offices constraint)
• Embargo rules filtering (hide recent data by office)
• Time window filtering (restrict historical data access)
• Data classification filtering (classification levels)
• Integration in TimeSeriesController
• Integration in TimeSeriesDaoImpl
• Logging for debugging and monitoring
• Backward compatibility (method overloads)
• Tests (unit tests for helpers, integration tests for DAO filtering)
• Documentation (inline comments and usage examples)

---

Steps to Validate

1. Start CWMS Data API with authorization proxy:

   # Ensure authorization proxy is running and sending x-cwms-auth-context header
   podman ps | grep authorizer-proxy

2. Test office access validation:

   # Request timeseries for office user has access to (should succeed)
   curl http://localhost:3001/cwms-data/timeseries?name=TEST.Flow.Inst.1Hour.0.Rev&office=SWT \
     -H "Authorization: Bearer $TOKEN"
   
   # Request timeseries for office user doesn't have access to (should fail with 400)
   curl http://localhost:3001/cwms-data/timeseries?name=TEST.Flow.Inst.1Hour.0.Rev&office=SPK \
     -H "Authorization: Bearer $TOKEN"

3. Test embargo filtering (requires OPA policy with embargo rules):

   # Recent data should be hidden for non-exempt users
   curl http://localhost:3001/cwms-data/timeseries?name=TEST.Flow.Inst.1Hour.0.Rev&office=SWT&begin=PT-24H \
     -H "Authorization: Bearer $TOKEN_NON_EXEMPT"
   
   # Recent data should be visible for embargo-exempt users (water managers)
   curl http://localhost:3001/cwms-data/timeseries?name=TEST.Flow.Inst.1Hour.0.Rev&office=SWT&begin=PT-24H \
     -H "Authorization: Bearer $TOKEN_WATER_MANAGER"

4. Test time window filtering (requires OPA policy with time_window constraint):

   # Dam operator with 8-hour time window restriction
   curl http://localhost:3001/cwms-data/timeseries?name=TEST.Flow.Inst.1Hour.0.Rev&office=SPK&begin=PT-48H \
     -H "Authorization: Bearer $TOKEN_DAM_OPERATOR"
   # Should only return last 8 hours, not full 48 hours requested

5. Check logs for filter application:

   # Controller logs
   podman logs data-api | grep "Authorization context"
   
   # DAO logs
   podman logs data-api | grep "Applied embargo filter"
   podman logs data-api | grep "Applied time window filter"

6. Verify backward compatibility (requests without authorization header):

   # Should work without authorization header (no filtering applied)
   curl http://localhost:7001/cwms-data/timeseries?name=TEST.Flow.Inst.1Hour.0.Rev&office=SWT

---

Local Environment Notes

• Backward compatible: Methods without authorization filters still work as before
• Optional filtering: Authorization filters only applied when x-cwms-auth-context header is present
• Performance: Filtering at database level using JOOQ conditions - no in-memory filtering
• Logging: FINE-level logs for debugging authorization decisions
• Integration: Designed to work with authorization proxy sending x-cwms-auth-context header

---

Impacted Areas in Application

• TimeSeriesController (office access validation, authorization filter instantiation)
• TimeSeriesDaoImpl (embargo and time window filtering in SQL queries)
• Helper classes (new AuthorizationContextHelper and AuthorizationFilterHelper)
• JOOQ queries (additional WHERE clause conditions for embargo and time window filtering)

---

Notes

• This PR is part of the larger authorization infrastructure project
• Works in conjunction with the authorization proxy from cwms-access-management repo
• Tests will be added in follow-up commits in this same PR
• Current implementation focuses on functionality and validation, where policy decisions come from CWMS Access Management

[MikeNeilson]

Overall it seems reasonable.

The initial Context helper processing should probably go in ApiServer.java, here:

cwms-data-api/cwms-data-api/src/main/java/cwms/cda/ApiServlet.java

Line 358 in 4d1d5b5

.before(authenticator)

after the authenticator, and they like the authenticator itself, or what you see on line 360, set a context attributed with the appropriate created object.

[MikeNeilson]

it would seem this and below should be one block that uses "requestedOffice" in the has and get methods.

[krowvin]

Do we have a means in the CWMS schema to determine if a given office has embargoRules?

Or is this more of a hold-over?

[MikeNeilson]

we still need to sort out exactly how that gets determined and then converted into a policy.