Admin Cockpit · Surface walkthrough

Meta · Privileged handoff

A per-surface walkthrough of the Admin Cockpit admin surface: layout, states, interactions, data, and cross-references.

drafted
8sections3 minread
Markdown source
On this page

Context. surface admin · domain meta · route /handoff · auth anon (public path; reads customer + admin cookies) · source apps/oshun/admin/src/app/handoff/page.tsx

Last walked. —

Purpose#

Public entry point for the privileged-handoff sign-in flow into the admin cockpit. Authenticated consumer-shell users exchange their consumer session for an admin session via this page; the actual elevation call is POST /api/admin/signin, dispatched from HandoffLauncher. Operators with a valid admin cookie are redirected to returnTo or /.

Entry points#

  • Public path — PUBLIC_PATHS in apps/oshun/admin/src/middleware.ts includes /handoff; no admin session required to reach it
  • Redirect target from /unauthorized (operator clicks "Return to handoff entry")
  • Redirect target after middleware miss — when /,/inbox, etc. bounce anonymous traffic via /unauthorized?reason=missing-session&returnTo=…, the operator navigates from there to /handoff
  • Direct URL — operator follows runbook instructions

Layout regions#

This page does NOT render AdminShell. It renders a plain <main role="main" className={styles.page}> containing:

  • Card (section.styles.card):
    • Eyebrow — "Oshun · Operations"
    • Heading — h1 "Privileged handoff"
    • Body — "The admin cockpit is entered through an explicit privileged handoff from the consumer shell. Authenticate with your consumer account, then request elevation for the admin surfaces your role grants."
    • Reason line — when searchParams.reason is set, renders <p className={styles.reason}>Reason: <readableReason>...</p> (mapping: missing-session / invalid-session / signed-out have explicit copy; other values rendered verbatim)
    • HandoffLauncher — receives hasCustomerSession, returnTo, requestId

States#

The page-level branching runs BEFORE rendering:

  • Has admin session already — parseAdminSessionToken(adminToken) returns valid; redirect to returnTo ?? '/' (never renders the card)
  • No admin session, no consumer session — hasCustomerSession === false; HandoffLauncher renders the missingSession role="status" block: "No consumer session cookie was detected. Sign in through the consumer shell (https://oshun.app) and then return here to request elevation."
  • No admin session, has consumer session — HandoffLauncher renders the primary action button
  • returnTo query param invalid — sanitizeReturnTo returns null when value doesn't start with /, starts with //, or starts with /unauthorized / /handoff
  • reason query param recognized — body shows readableReason(value):
    • missing-session → "No admin session was present — request a new handoff."
    • invalid-session → "Admin session expired or failed verification."
    • signed-out → "You signed out of the admin cockpit."
    • other values → rendered verbatim
  • HandoffLauncher submit idle — Button label "Request admin handoff"
  • HandoffLauncher submit submitting — Button label "Requesting handoff…"; disabled
  • HandoffLauncher submit error — <p role="alert"> with the error message (typed body.message from response or Handoff failed (HTTP <status>).)
  • HandoffLauncher submit success — <p role="status"> "Handoff granted. Redirecting to <redirectTo>…"; calls window.location.assign(redirectTo)

Interactions#

  • "Request admin handoff" (button — primary action)
    • Function: submit() → fetch('/api/admin/signin', { method: 'POST', credentials: 'same-origin', headers: { 'content-type': 'application/json', 'x-request-id': requestId ?? '' }, body: JSON.stringify({ returnTo }) })
    • Disabled while status.kind === 'submitting'
    • On response.ok + body.ok === true, sets success with body.redirectTo (defaults to '/') and triggers window.location.assign(redirectTo)
    • Error path uses body.message when present, else "Handoff failed (HTTP )."
  • (no consumer session) prompt — no button; static copy pointing operators to sign in through the consumer shell at https://oshun.app

Data & contracts#

  • Reads:
    • cookies() from next/headers — OSHUN_ADMIN_SESSION_COOKIE_NAME, OSHUN_CONSUMER_SESSION_COOKIE_NAME
    • parseAdminSessionToken(adminToken) — returns parsed session or null
    • headers().get('x-request-id') — propagates from middleware (see shell/02-routing-layouts.md)
    • searchParams (Promise) — returnTo, reason
  • Writes: POST /api/admin/signin with { returnTo } JSON body and x-request-id header; expected response shape { ok: true, redirectTo?: string, message?: string }
  • Realtime: None.
  • Auth/role check: NO middleware session check — /handoff is in PUBLIC_PATHS. The page itself uses cookie presence and parseAdminSessionToken to decide what to render

Cross-references#

  • Shell: shell/03-auth-session.md (sign-in flow lives here), shell/02-routing-layouts.md (public paths list)
  • Sibling meta route: unauthorized.md (the page that bounces operators back here)
  • Session cookie module: apps/oshun/admin/src/lib/session-cookie.ts
  • Customer cookie module: apps/oshun/admin/src/lib/customer-session.ts
  • Component source: apps/oshun/admin/src/app/handoff/HandoffLauncher.tsx

Open questions / known gaps#

  • Document the upstream service backing POST /api/admin/signin — what authentication / authorization it performs to validate the consumer session for elevation
  • sanitizeReturnTo blocks /unauthorized and /handoff to prevent loops; verify whether any other paths should be blocked (e.g., /__test/*)
  • No CSRF protection visible on the form submit — verify the BFF endpoint requires double-submit cookie or origin check