---
path: /handoff
surface: admin
domain: meta
auth: anon (public path; reads customer + admin cookies)
source: apps/oshun/admin/src/app/handoff/page.tsx
status: drafted
last_walked: '—'
---

# Meta · Privileged handoff

## 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
    <status>)."
- [ ] **(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