V1 Web PWA · Surface walkthrough

Studio · Authentication Architecture

A per-surface walkthrough of the V1 Web PWA studio surface: layout, states, interactions, data, and cross-references.

walked
9sections3 minread
Markdown source
On this page

Context. surface studio · domain governance · route /studio/authentication-architecture · auth signed-in + studio entitlement · source apps/oshun/web/src/app/studio/authentication-architecture/page.tsx

Last walked. 2026-05-29 automated runtime walk (Playwright headless) — render, /v1 data (2xx), console/page-errors, expected content, screenshot verified; live screen-reader, touch, offline, and telemetry-delivery checks pending a manual AT pass. Evidence: WALKTHROUGH/results/runtime-sweep-2026-05-29.md; body re-derived 2026-06-03 from current source (lane-console architecture); 2026-06-25 route-state addendum closed loading/unauthorized/error/ready, pending evaluate, result-table, validation, footer, and real-BFF Playwright coverage. Evidence: WALKTHROUGH/results/v1-real-infra-run-2026-06-22.md §105; apps/oshun/web/e2e/studio-authentication-architecture.spec.ts

Purpose#

Decide login sessions with the real authentication policy evaluator: the Authentication Policy Lane returns allow / challenge / deny per session by factor count, MFA, password age, and device/location signals, with a 0–100 risk score. It is a live admin console wired to /v1/admin/studio/auth-policy, not an in-page simulation.

Entry points#

  • Direct URL / bookmark — /studio/authentication-architecture (signed-in + studio entitlement; admin scope required to evaluate)
  • Sibling Studio routes — reached via the quick-action panel on color-system, rbac-permission-policy, enterprise-tenant-isolation, and other governance pages

Layout regions#

page.tsx mounts <ShellLayout active="studio"> and renders <StudioAuthenticationArchitectureWorkspace /> followed by a single panel of quick-action links.

  • Shell: ShellLayout chrome with the Studio tab active
  • Workspace heading: WorkspaceHeading renders the page <h1> "Studio Authentication Architecture", followed by the data-authentication-architecture-summary paragraph
  • Authentication Policy Lane: an <h2> data-auth-lane-heading ("Authentication Policy Lane") section with the load states and, when ready, the evaluate form and result table
  • Quick-actions panel: data-auth-footer with data-auth-footer-link-count="9" and 9 sibling quickAction Links — Session and Device Management, RBAC and Permission Policy UX, Enterprise Tenant Isolation, Audit and Compliance Surfaces, Notification Center, Activity and Change Feeds, "Back to Multi-Project Operations workspace", "Back to Workspace Context Switching workspace", and "Back to Cross-Domain Entity Model workspace". Each link exposes data-auth-footer-link and a 44px minimum touch target. No self-link and no Route Map panel.

States#

  • Loading — data-auth-loading ("Loading auth evaluator…")
  • Unauthorized — data-auth-unauthorized ("Access restricted.") on 401/403
  • Error — data-auth-error ("Could not load the auth evaluator.")
  • Ready / form — data-auth-enums ("N decisions · M reasons") plus the data-auth-form evaluate form with data-auth-form-state="idle"
  • Pending evaluate — data-auth-form-state="evaluating" while the POST is in flight; data-auth-submit is disabled, aria-disabled="true", and aria-busy="true" with "Evaluating sessions…" copy
  • Result — data-auth-result headline (data-auth-headline with the data-auth-count allow/challenge/deny spans) and the data-auth-sessions table of data-auth-session-row rows (data-auth-session-reason, data-auth-session-risk, data-auth-session-id, data-auth-session-decision)
  • Evaluate error — data-auth-evaluate-error for invalid JSON or a non-200 response

Interactions#

  • Auth (JSON) — textarea data-auth-payload, aria-label="auth json", seeded with policy fields (minFactors, requireMfa, maxPasswordAgeDays) and sessions[] fields (sessionId, factors, MFA, password age, device trust, and anomalous-location signal)
  • Evaluate sessions — button data-auth-submit (type="submit"); POSTs the parsed JSON to /v1/admin/studio/auth-policy/evaluate, setting data-auth-result on a 200 with a valid result, or data-auth-evaluate-error otherwise
  • Quick-action links — each quickAction Link under data-auth-footer navigates to its sibling Studio route (see Layout regions for the 9 targets)

Data & contracts#

  • Reads: GET /v1/admin/studio/auth-policy on mount — returns the catalog (authDecisions[], authReasons[])
  • Writes: POST /v1/admin/studio/auth-policy/evaluate — returns { result: { sessions[], summary{ allowCount, challengeCount, denyCount } } }
  • Realtime: none
  • Caching: client fetch with cache: 'no-store'; buildBffAuthHeaders() attaches the bearer token
  • Auth/role check: admin-scoped fail-closed — admin:* or admin:studio, 401/403 under the studio workspace gate

E2E coverage#

  • apps/oshun/web/e2e/studio-authentication-architecture.spec.ts
  • Covers admin direct navigation, real GET /v1/admin/studio/auth-policy catalog load, default-payload evaluation through the live BFF, session result rows, malformed JSON with zero POSTs, valid-but-invalid payloads surfacing the live BFF 400 detail, pending submit lockout/busy state, catalog loading/error, flat footer targets/touch targets, and non-admin unauthorized fail-closed behavior.

Cross-references#

Open questions / known gaps#

  • Current page keeps the flat quick-action footer; no breadcrumb or Route Map panel is present for this route-state slice.
  • Current evaluator consumes caller-supplied session signal JSON over the real admin BFF. A live login-telemetry feed for device trust and anomalous location remains a product gap to define before this lane can run from production authentication events without pasted/requested payloads.