2026-05-22 21:45:30 +02:00
|
|
|
# UI Handoff Contracts
|
|
|
|
|
|
|
|
|
|
Future self-service and scope-admin UIs should consume user-engine through a
|
|
|
|
|
transport adapter that preserves the service shapes below.
|
|
|
|
|
|
2026-06-15 23:39:34 +02:00
|
|
|
USER-WP-0014 adds `RegistrationAccessManagementUi` as the first implemented
|
|
|
|
|
headless UI contract facade. It returns transport-neutral screen models,
|
|
|
|
|
route definitions, responsive layout metadata, and an accessible HTML
|
|
|
|
|
verification renderer.
|
|
|
|
|
|
2026-05-22 21:45:30 +02:00
|
|
|
## Self-Service Account UI
|
|
|
|
|
|
|
|
|
|
Required backend operations:
|
|
|
|
|
|
|
|
|
|
- `me` to resolve the current actor, user, account, and identity links.
|
2026-06-15 23:39:34 +02:00
|
|
|
- `RegistrationAccessManagementUi.start_registration` to create a UI-backed
|
|
|
|
|
registration session.
|
|
|
|
|
- `RegistrationAccessManagementUi.attach_factor` to attach adapter-supplied
|
|
|
|
|
factor evidence without rendering factor values.
|
|
|
|
|
- `RegistrationAccessManagementUi.complete_registration` to enforce UI
|
|
|
|
|
terms/consent and complete the headless registration flow.
|
|
|
|
|
- `RegistrationAccessManagementUi.prepared_rights_review` and
|
|
|
|
|
`accept_prepared_claim` to review and claim prepared rights.
|
|
|
|
|
- `RegistrationAccessManagementUi.hat_selection_view` and `select_hat` to show
|
|
|
|
|
available hats and select active access context.
|
2026-05-22 21:45:30 +02:00
|
|
|
- `effective_profile` with the actor tenant and optional application id.
|
|
|
|
|
- `projection` with `SELF_SERVICE` for editable user-visible fields.
|
|
|
|
|
- `set_profile_value` for fields whose catalog mutability includes `USER`.
|
|
|
|
|
- `audit_records` or a filtered audit transport for recent user-visible
|
|
|
|
|
account activity.
|
|
|
|
|
|
|
|
|
|
## Scope Admin UI
|
|
|
|
|
|
|
|
|
|
Required backend operations:
|
|
|
|
|
|
|
|
|
|
- `resolve_tenant_context` before all tenant-scoped screens.
|
2026-06-15 23:39:34 +02:00
|
|
|
- `RegistrationAccessManagementUi.admin_dashboard` for registration,
|
|
|
|
|
prepared-account, access-profile, and onboarding diagnostics.
|
2026-05-22 21:45:30 +02:00
|
|
|
- `set_tenant_account_status` for in-scope account state.
|
|
|
|
|
- `add_membership` for tenant/team membership changes.
|
|
|
|
|
- `projection` with `ADMIN` or a future admin transport projection.
|
|
|
|
|
- `tenant_diagnostics` for onboarding and support readiness checks.
|
|
|
|
|
|
2026-06-15 23:39:34 +02:00
|
|
|
## UI Route Contract
|
|
|
|
|
|
|
|
|
|
`RegistrationAccessManagementUi.api_contract()` defines these route ids:
|
|
|
|
|
|
|
|
|
|
- `registration.start`
|
|
|
|
|
- `registration.factor`
|
|
|
|
|
- `registration.complete`
|
|
|
|
|
- `prepared_account.review`
|
|
|
|
|
- `prepared_account.accept`
|
|
|
|
|
- `prepared_account.deny`
|
|
|
|
|
- `access_profile.select_hat`
|
|
|
|
|
- `admin.dashboard`
|
|
|
|
|
|
|
|
|
|
Transport adapters may map these ids to HTTP, RPC, desktop, or CLI routes.
|
|
|
|
|
The route contract marks factor values, prepared-account factor matches,
|
|
|
|
|
profile defaults, claim values, and hidden policy details as redacted.
|
|
|
|
|
|
|
|
|
|
## Accessibility And Responsive Contract
|
|
|
|
|
|
|
|
|
|
`render_html` emits `banner`, `navigation`, and `main` landmarks. Section
|
|
|
|
|
navigation uses labels, controls expose `aria-label`, and screen models include
|
|
|
|
|
mobile and desktop layout metadata. Mobile screens use a one-column layout and
|
|
|
|
|
44px minimum touch target. Desktop screens use a two-column workbench layout.
|
|
|
|
|
|
2026-05-22 21:45:30 +02:00
|
|
|
## Fixtures
|
|
|
|
|
|
|
|
|
|
Use `user_engine.testing.scenarios` for human, tenant admin, platform
|
|
|
|
|
operator, delegated agent, invalid, expired, local issuer, and missing-tenant
|
|
|
|
|
fixtures. UIs should keep fixtures at the transport boundary and avoid
|
|
|
|
|
embedding identity-provider logic.
|
2026-09-12 10:34:44 +02:00
|
|
|
|
|
|
|
|
## Account recovery
|
|
|
|
|
|
|
|
|
|
`/access-recovery` is public and never starts OIDC automatically. It distinguishes
|
|
|
|
|
an unverified visitor from a verified current portal session, and exposes account
|
|
|
|
|
and logout controls. Browser errors strip callback query parameters before
|
|
|
|
|
reaching it. `/onboarding` shows the verified identity, sign-in tenant and roles,
|
|
|
|
|
personal tenant memberships and recorded application/service/workload/asset
|
|
|
|
|
memberships. These are the current user's records, not a fleet-wide entitlement
|
|
|
|
|
inventory or a grant to every application in a tenant. No workload record means
|
|
|
|
|
unknown/unrecorded access, not an inferred denial or grant.
|
|
|
|
|
|
|
|
|
|
POST `/logout` keeps its CSRF-protected local logout. With `scope=shared` it clears
|
|
|
|
|
the portal session and sends the browser to the configured issuer's
|
|
|
|
|
`/account/logout` confirmation, followed by provider-owned sign-out. No supplied
|
|
|
|
|
return URL is accepted. Other RP sessions and already issued JWTs may remain
|
|
|
|
|
valid. KEY-WP-0034 owns issuer confirmation; USER-WP-0026 tracks this recovery.
|
