[FEATURE]: External group to team mapping seam + in-core mapping table

[jonpspri]

Epic: #5885 | Added: 2026-07-29 per ultimate-user feedback

Depends on: #5895 (Epic 1 gate). Blocks: #5900, #6272.

What

External IdP tokens carry group memberships (e.g., Entra group object ID GUIDs) that never match ContextForge team IDs. This story adds the translation layer so Layer-1 token scoping keeps working unchanged in trust mode:

• Idempotent Alembic migration + ORM model for external_group_mappings: issuer, tenant (nullable), external_group_id, cf_team_id (FK→teams), cf_role (nullable String, validated against the roles table at write time — NOT a foreign key; the roles.name partial unique index forbids one. See Group-to-role mapping below), validation_status / last_validated_at; unique on (issuer, tenant, external_group_id).
• A single shared resolver resolve_external_groups_to_teams(issuer, tenant, groups, db) invoked by the trust branch after claims extraction, before token_teams is computed. Unmapped groups contribute nothing — fail-closed. When cf_role is populated the resolver additionally returns the associated role names so that Layer-2 RBAC can be satisfied without a native roles claim in the JWT (consumed by Claims extraction module + trust-mode virtual principal contract #5899 / Trust-mode branch in get_current_user (skip user lookup, keep jti revocation) #5900).
• The seam's contract is documented so a cpex plugin can later implement the same interface (follow-up: [FEATURE]: HTTP claims-mapping hook — post-verification, pre-scoping identity transformation point contextforge-org/cpex#140, Consume cpex claims-mapping hook for external group → team mapping in JWT-trust mode #5975 — plugin dispatch itself is out of scope here).
• Admin CRUD API for mapping rows (RBAC-scoped), with write-time existence validation of the external group via the app-only Graph client ([FEATURE]: Entra group-overage support - app-only Graph client + resolution cache #5977 story). Graph unreachable → warn-and-allow, audit-logged, validation_status="unknown".

Group-to-role mapping (BASF requirement)

Entra group membership must drive both Layer-1 (team visibility) and Layer-2 (invocation permission) authorisation decisions without requiring the Entra token to carry ContextForge-native role names. The cf_role column on external_group_mappings enables this:

• When cf_role is NULL the row contributes only to token_teams (unchanged behaviour).
• When cf_role is non-NULL the resolver annotates the virtual principal with that role, which the trust-mode path (Claims extraction module + trust-mode virtual principal contract #5899, Trust-mode branch in get_current_user (skip user lookup, keep jti revocation) #5900) merges with any roles claim present in the token. The combined role set is then resolved against the server-side roles table per the existing resolution rule.
• This is the mechanism by which a deployment (e.g., BASF) can map a single Entra group GUID to both a CF team and the developer (or viewer) role that grants a2a.invoke, without any change to the Entra token's claims.
• The full treatment of group→role resolution for trust mode is tracked as a separate blocking story: [BUG]: /admin/llm/* and /v1/admin/llm/* diverge on CSRF validation immediately after login #5978.

Deployment contract

For per-agent invocation isolation, agents MUST be registered with visibility = "team" and assigned to a dedicated CF team. visibility = "public" agents are accessible to all authenticated callers regardless of token_teams — the Layer-1 gate does not apply. Deployers who require per-agent isolation (e.g., Agent A accessible only to AgentA-Team members) must set visibility = "team". This constraint must be documented in the trust-mode deployment guide (story #5906 docs sweep).

Must NOT

• No redesign of the two-layer model — mapping feeds Layer-1 token_teams; Layer-2 RBAC untouched.
• No periodic background group-metadata sync (deleted groups fail closed structurally; periodic revalidation is deferred to extension-module work, Extension module framework — dynamically imported integration packages #5862).
• Raw external group IDs must never reach token_teams.

Acceptance criteria

• Single alembic head; migration up/down/up clean on SQLite and Postgres, including the new cf_role nullable column.
• uv run pytest tests -k "group_mapping or external_group" -q green, including fail-closed and CRUD deny-path cases (unauthenticated, wrong team, insufficient permissions).
• Trust-mode request with mapped Entra group GUIDs yields token_teams = mapped CF team IDs (integration test through the funnel branch; strict-xfail until Trust-mode branch in get_current_user (skip user lookup, keep jti revocation) #5900 lands).
• AC-visibility-gate: Two integration tests covering agent visibility semantics:
  • Team-visibility isolation: Agent-A (visibility=team, team=CF-Team-A) and Agent-B (visibility=team, team=CF-Team-B). Caller token maps only to CF-Team-A. POST /a2a/agent-a/invoke → 200; POST /a2a/agent-b/invoke → 404 (404-not-403 convention per existing _check_agent_access behaviour to avoid leaking agent existence).
  • Public-visibility baseline: Both agents set visibility=public. Both invocations → 200. Documents the deliberate behaviour that public agents are accessible platform-wide regardless of team membership.
• AC-e2e-team-isolation: Full end-to-end test (strict-xfail until Trust-mode branch in get_current_user (skip user lookup, keep jti revocation) #5900 lands):
  1. Create CF-Team-A and CF-Team-B; register Agent-A (team=CF-Team-A, visibility=team) and Agent-B (team=CF-Team-B, visibility=team).
  2. Insert external_group_mappings row: Entra-Group-GUID-1 → CF-Team-A; cf_role = developer.
  3. Mint trust-mode JWT with groups=[Entra-Group-GUID-1].
  4. POST /a2a/agent-a/invoke → 200; POST /a2a/agent-b/invoke → 404.
• AC-e2e-no-mapping: Trust-mode JWT carrying an Entra group GUID with no external_group_mappings row → token_teams = [] → any visibility=team agent → 404; visibility=public agents → 200.

[jonpspri]

♻️ Direction Change: Periodic revalidation via extension module (#5862) — reconsider in favour of CEL

The "Must NOT" section of this issue explicitly defers periodic group-metadata sync (deleted group revalidation) to the extension-module framework: "No periodic background group-metadata sync... periodic revalidation is deferred to extension-module work, #5862."

#5862 will not be implemented. It is being closed in favour of achieving extensibility through configurable CEL expressions, per the direction in #6408 (Security Policy Engine and Generalization).

What this means for the deferred revalidation requirement

The security concern is real: a deleted Entra group should eventually stop granting access even if it never re-appears in a token. The issue body correctly notes that "deleted groups fail closed structurally (the verified token is the authority; Entra stops emitting deleted group IDs)", which means the fail-closed behaviour is already correct for the common case. The extension module was being held as the vehicle for the proactive revalidation hygiene on top.

CEL as the alternative

Instead of a background task in a dynamically-loaded extension module, revalidation policy can be expressed as a CEL guard on the mapping row evaluated at trust-mode verification time:

// Reject mapping rows whose last_validated_at is older than 7 days
// (evaluated per-row in the resolver; "now" injected by the runtime)
now - mapping.last_validated_at < duration("168h")

This gives operators a configurable staleness window without a background task, a separate process, or the safe-loading complexity of #5862. The validation_status and last_validated_at columns this issue already provisions are exactly the inputs such an expression needs.

For deployments that do want proactive Graph revalidation on a schedule, a lightweight scheduled job (a Kubernetes CronJob, a simple APScheduler task, or a one-shot admin API endpoint) is a lower-risk delivery vehicle than a dynamically-imported extension module — and it can call the same Graph client this issue already plans for write-time validation.

Recommended update to this issue

• Remove the hard dependency on Extension module framework — dynamically imported integration packages #5862 from the "Must NOT" list.
• Note that the CEL expression seam (defined under Security Policy Engine and Generalization #6408) will provide the policy hook that previously required an extension module.
• The in-core mapping table, resolver logic, and write-time Graph validation remain fully in scope and unaffected.

[jonpspri]

Requirement change note — three items

1. Uniqueness. The plain unique constraint let duplicate rows where tenant is NULL. A partial unique index now covers those rows (WHERE tenant IS NULL). The service also checks for duplicates on create and update.
2. Cache. Create, update, and delete now invalidate the external-identity cache.
3. Graph validation status. A 404 answer gives validation_status="graph_group_not_found". The row is allowed. The resolver fails closed at read time, and Entra GUIDs are never reused. A Graph error gives "unknown" with a warning, as the issue text says. The validator is wired on PR feat(auth): resolve service-principal group membership via Graph for app-only trust tokens #6757.