[FEATURE]: HTTP claims-mapping hook — post-verification, pre-scoping identity transformation point

[jonpspri]

Context

ContextForge (IBM/mcp-context-forge) is adding a config-gated JWT-trust authentication mode (epic IBM/mcp-context-forge#5885), in which a properly-signed token from a trusted external IdP authorizes requests from its claims alone, with no local user record. One open design point: external group memberships (for example, Entra group object IDs in a groups claim) must be translated into ContextForge team identifiers before Layer-1 token scoping computes resource visibility.

Why the existing HTTP hooks can't carry this

• HTTP_PRE_REQUEST fires before authentication; no verified claims exist yet.
• HTTP_AUTH_RESOLVE_USER is a full replacement authentication path whose result is re-resolved against the local user database — incompatible with trust mode's no-local-user premise, and using it would force the plugin to re-implement token verification, revocation, and claims extraction.
• HTTP_AUTH_CHECK_PERMISSION is Layer-2 (per-route permission checks); its payload carries no token claims, and it never governs Layer-1 visibility filtering, which happens in the service layer.

The missing seam is post-verification, pre-scoping: verified claims in hand, team/visibility resolution not yet performed.

Proposal

A new HTTP hook type — HTTP_AUTH_MAP_CLAIMS as a working name, open to bikeshedding:

• Payload: issuer, tenant (where derivable), canonical user ID, the raw groups claim value, the full verified claims set (read-only), and the auth method.
• Result: the effective team-identifier list (and optionally role names), or an explicit denial with a reason.
• Semantics: invoked only when the deployment opts in. No plugin decision, plugin error, or timeout falls back to the caller's documented default — fail-closed for the trust-mode use case.
• Hot path: runs per authenticated request, so the contract should document caching expectations for implementers (e.g., decisions keyed by a hash of the relevant claims).

Security posture

This would be the first hook able to influence Layer-1 visibility (what a caller can see), not just Layer-2 permissions. Worth spelling out in the contract:

• Opt-in per deployment; absent configuration, the hook is never consulted.
• A grant-side plugin mistake broadens visibility, so the trust bar should be stated explicitly alongside the existing allowlisted-load-path posture.
• Decisions are logged with plugin identity, following the existing metrics/metadata patterns used by the permission hook.

Non-goals

• Background or periodic work (group-metadata synchronization with an IdP, Entra group-overage lookups). cpex hooks are request-scoped by design; that class of integration belongs to ContextForge's extension-module proposal ([EPIC][CORE]: Extension module framework — dynamically imported integration packages IBM/mcp-context-forge#5862).
• IdP-specific clients (Microsoft Graph and friends) inside cpex itself.

Deliverables

• Hook enum value plus payload/result models with validation.
• Framework documentation: contract, caching guidance, security considerations.
• Unit tests mirroring the existing HTTP hook coverage.

The ContextForge consumer side is tracked separately in IBM/mcp-context-forge (cross-link to be added once filed).

[jonpspri]

Consumer side is now filed: IBM/mcp-context-forge#5975.