cameleer-server/docs/superpowers/specs/2026-04-14-claim-mapping-rules-editor-design.md

# Claim Mapping Rules Editor

## Problem

The server has a claim mapping rules engine (`ClaimMappingService`) that maps arbitrary JWT claims to Cameleer roles and groups during OIDC login. The backend API exists (`/api/v1/admin/claim-mappings` CRUD), but there is no UI for managing these rules. Admins must use curl or Swagger to create, edit, and delete rules.

## Solution

Add a rules editor modal to the existing OIDC config page (`/admin/oidc`), triggered from the Claim Mapping section. The modal contains a compact rules table with inline CRUD and a collapsible server-side test panel.

## Design

### Trigger

An "Edit Rules" button added to the bottom of the existing Claim Mapping section on the OIDC config page. Displays a badge with the active rule count (e.g. "3 active rules"). Visible in both read and edit mode of the OIDC form — the rules modal manages its own state independently of the OIDC form's edit/save lifecycle.

### Modal — Rules Table

A full-width modal dialog with the title "Claim Mapping Rules" and a subtitle explaining their purpose.

**Table columns:**

| Column | Content | Width |
|--------|---------|-------|
| `#` | Priority number (display only, derived from order) | 30px |
| Claim | Claim name in monospace code style | auto |
| Match | Match type pill: `equals`, `contains`, `regex` | auto |
| Value | Match value in monospace | auto |
| Action | Action pill: `assign role` (green/success), `add to group` (amber) | auto |
| Target | Role name or group name | auto |
| Actions | Reorder arrows + edit pencil + delete x | ~80px |

**Action icons per row:**

- Up/down arrow buttons for reordering. Up hidden on first row, down hidden on last row. Moving a rule swaps priorities locally (saved to server on Apply).
- Pencil icon switches the row to inline edit mode (same field layout as the add row).
- X icon deletes the rule locally after a `ConfirmDialog` confirmation (saved to server on Apply).

**Inline add form:**

A row at the bottom of the table with input fields matching the table columns:

- `Input` — claim name (text, placeholder "Claim name")
- `Select` — match type (equals / contains / regex)
- `Input` — match value (text, placeholder "Match value")
- `Select` — action (assign role / add to group)
- `Select` — target, populated from existing roles (when action is "assign role") or existing groups (when action is "add to group"). Includes a placeholder option ("Select role..." / "Select group..."). Switching action resets the target selection.
- `Button` — "+ Add" (disabled until claim, value, and target are filled)

New rules are assigned a priority one higher than the current maximum.

**Inline edit mode:**

When the pencil icon is clicked, the row's static cells become editable inputs (same controls as the add form, including the target Select dropdown). The action icons change to a checkmark (save) and x (cancel). Saving updates local state only — persisted to server on Apply.

**Empty state:**

When no rules exist, show a centered message: "No claim mapping rules configured. Rules let you assign roles and groups based on JWT claims." with the add form below.

### Modal — Test Panel

A collapsible section at the bottom of the modal, separated by a heavier border. Collapsed by default. Toggle via a clickable header row showing "Test Rules — Paste a decoded JWT to preview which rules would fire".

**Layout when expanded:**

Side-by-side split:

- **Left:** `textarea` for pasting decoded JWT claims as JSON. Placeholder shows a sample JSON object.
- **Right:** Results panel with:
  - Each matched rule listed: rule number, claim name, match description, arrow, action and target
  - "Effective" summary line: combined roles and groups
  - If no rules matched: "No rules matched — would fall back to default roles: [roles]"

**"Test" button** below the textarea triggers `POST /api/v1/admin/claim-mappings/test`. The evaluation runs server-side using `ClaimMappingService.evaluate()` — the same code path as the production OIDC login flow in `OidcAuthController.applyClaimMappings()`.

**Visual feedback:** While test results are displayed, matched rows in the table above get a subtle green background tint and a checkmark in place of their action icons.

### Local Edit + Apply Pattern

All changes (add, edit, delete, reorder) modify local state only. No API calls are made until the admin clicks Apply.

- **On modal open:** server rules are cloned into local state.
- **Cancel:** discards all local changes and closes the modal.
- **Apply:** diffs local state against server state — creates new rules (temp IDs), updates changed rules, deletes removed rules. On success, shows a toast and closes the modal. On failure, shows an error toast and keeps the modal open.

### Reordering

Up/down arrow buttons on each row. Clicking an arrow swaps the priority values of two adjacent rules in local state.

Priority is a server-side integer. The UI displays it as the row number (`#` column) — admins never edit the number directly.

### New Backend Endpoint

```
POST /api/v1/admin/claim-mappings/test
Content-Type: application/json
Authorization: Bearer <admin-token>

{
  "sub": "user-42",
  "email": "jane@acme.com",
  "department": "engineering",
  "groups": ["frontend", "design"]
}

Response 200:
{
  "matchedRules": [
    {
      "ruleId": "uuid",
      "priority": 1,
      "claim": "email",
      "matchType": "regex",
      "matchValue": ".*@acme\\.com$",
      "action": "assignRole",
      "target": "OPERATOR"
    }
  ],
  "effectiveRoles": ["OPERATOR"],
  "effectiveGroups": [],
  "fallback": false
}
```

The endpoint:

- Requires ADMIN role (same as other claim mapping endpoints)
- Loads all rules from the database
- Calls `ClaimMappingService.evaluate(rules, claims)` — production code path
- Maps `MappingResult` list to the response DTO
- Returns `fallback: true` when no rules matched (UI shows default roles message)
- Read-only — no side effects, no user creation, no role assignment

### Error Handling

- **Invalid JSON in test textarea:** Show inline validation error, disable Test button
- **API errors on CRUD:** Toast notifications (consistent with rest of admin UI)
- **ConfirmDialog on delete:** Type-to-confirm not needed for rules (they're low-risk, easily recreated). Simple "Delete this rule?" confirm/cancel.

## Files to Create/Modify

### Backend

- `ClaimMappingAdminController.java` — add `POST /test` endpoint
- New DTO for test response (inline record or separate class)

### Frontend

- New component: `ClaimMappingRulesModal.tsx` — the modal with table, inline CRUD, and test panel
- New CSS module: `ClaimMappingRulesModal.module.css`
- New API hooks: `useClaimMappingRules()`, `useCreateRule()`, `useUpdateRule()`, `useDeleteRule()`, `useTestRules()` — React Query hooks for the claim mapping API
- Modify: `OidcConfigPage.tsx` — add "Edit Rules" button in the Claim Mapping section, render the modal

### Not in Scope

- Drag-and-drop reordering (up/down arrows are sufficient for 1-10 rules)
- Groups Claim field (rules can already match any claim including group claims)
- Bulk import/export of rules
- Rule templates or presets

## Visual Reference

Mockups available in `.superpowers/brainstorm/172364-1776174996/content/`:

- `claim-rules-modal.html` — initial layout (trigger button + table)
- `claim-rules-modal-v2.html` — full modal with test panel expanded and match highlighting