user-engine/docs/ui-contracts.md

UI Handoff Contracts

Future self-service and scope-admin UIs should consume user-engine through a transport adapter that preserves the service shapes below.

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.

Self-Service Account UI

Required backend operations:

• me to resolve the current actor, user, account, and identity links.
• 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.
• 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.
• RegistrationAccessManagementUi.admin_dashboard for registration, prepared-account, access-profile, and onboarding diagnostics.
• 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.

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.

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.

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.