[feat] aruna-auth: Authentication and Authorization Implementation

[lfbrehm]

Goal

Implement the aruna-auth crate providing authentication and authorization services for Aruna V3. This is a collection of state machines that are responsible for validating OIDC tokens, enforcing path-based role permissions, and maintaining the roaring bitmap indexes used for authorization-filtered search across the distributed system.

Core capabilities:

• OIDC token validation against configurable identity providers
• Aruna token creation, serialization and validation
• Path-based permission engine with wildcard support and deny-overrides-allow semantics
• Persistent storage of permission rules using Fjall
• Roaring bitmap generation and maintenance for search-time authorization filtering
• Integration with aruna-orga to react to group/role membership changes

---

Workplan

1. OIDC and Aruna Tokens

• Integrate with configurable OIDC providers (at minimum one for CI, extensible for production)
• Validate JWT signatures against provider JWKS endpoints
• Extract claims (subject, groups, roles) from validated tokens
• Cache JWKS keys with appropriate refresh logic

2. Permission Engine

• Implement path-based rule matching using globset
• Support middle * for single-segment wildcards and trailing ** for recursive matching
• Implement deny-overrides-allow rule evaluation semantics

3. Fjall Permission Storage

• Store and retrieve permission rules persistently via Fjall
• Support efficient lookup by subject
• Handle rule insertion, deletion, and enumeration

4. Roaring Bitmap Index

• Generate per-resource or per-path roaring bitmaps encoding which subjects have access
• Maintain bitmaps incrementally as permission rules are added or removed
• Expose bitmaps for consumption by aruna-metadata at search time

Definition of Done

• OIDC token validation implemented and tested against a mock provider
• Aruna token validation implemented and tested
• Permission engine correctly evaluates allow/deny rules with wildcard path patterns
• Fjall storage layer persists and retrieves permission rules reliably
• Roaring bitmap indexes generated correctly for a given permission rule set
• All public interfaces abstracted behind state machines with mock implementations available
• Integration verified with aruna-metadata consuming bitmaps for authorization-filtered search

---

Test Concept

Unit Testing

Each component (token validation, permission engine, storage, bitmap generation) is tested independently. Network and storage dependencies are abstracted behind state machines allowing mock injection. Target coverage >80% for core logic paths.

Integration Testing

Verify end-to-end authorization flows in the multi-node test harness:

• A user with a valid OIDC or Aruna token can access resources they have permission for
• A user without permission is correctly denied
• Permission revocation results in updated bitmaps and denied access at the next search/access attempt

---

Risks / Blockers

Technical risks:

• OIDC provider availability in CI: Mitigation — use a lightweight mock OIDC provider (local stub) for all automated tests; document real-provider configuration separately
• JWKS key rotation edge cases: Mitigation — implement explicit cache invalidation and add test scenarios for key rotation
• Roaring bitmap memory usage at scale (many roles × large indexes): Mitigation — measure during integration tests and evaluate sparse bitmap optimizations if needed

Design questions to resolve:

• Bitmap granularity: per-resource-path vs. per-realm-level aggregations — needs validation against aruna-metadata query patterns
• Rule storage schema in Fjall: key layout for efficient subject-based and path-based lookups needs finalization before implementation begins

Dependencies:

• aruna-metadata: Must confirm bitmap consumption API to ensure generated indexes are in the correct format
• Mock OIDC provider: Must be selected and configured before token validation work begins

Scope boundaries:

• Multi-realm federation is explicitly out of scope; single realm only
• Policy engine (DR-007) is deferred to post-MVP
• Full OAuth 2.0 flows (authorization code, device flow, etc.) are out of scope; token validation only

[lfbrehm]

related PR introduces a first iteration for authorization and authentication