Shell: Auth and session

Source: apps/oshun/admin/src/lib/session-cookie.ts, apps/oshun/admin/src/lib/server-session.ts, apps/oshun/admin/src/lib/customer-session.ts, apps/oshun/admin/src/app/handoff/page.tsx, apps/oshun/admin/src/app/handoff/HandoffLauncher.tsx, apps/oshun/admin/src/app/unauthorized/page.tsx, libs/oshun/navigation/src/admin-ia.ts (OSHUN_ADMIN_WORKSPACE_MODEL.requiredScopes, canEnterAdminWorkspace)

How an operator becomes an operator — the privileged handoff, the session cookie, the scopes, and the unauthorized fallback.

Three cookies you need to know#

The admin and consumer cookies are scoped separately. A customer session alone does NOT confer admin access — explicit privileged handoff is required.

Auth states#

• anonymous — no cookies; gated paths bounce to /unauthorized
• customer-only — only the consumer cookie; visiting an admin path bounces to /unauthorized?reason=missing-session; visiting /handoff offers the privileged-handoff flow
• admin (valid) — admin cookie parses cleanly; can access any path their scopes allow
• admin (invalid) — admin cookie present but parseAdminSessionToken returns null; middleware deletes the cookie and bounces to /unauthorized?reason=invalid-session
• admin + insufficient scope for workspace — middleware lets the request through (it only checks for any valid admin session), but the page's WorkspaceEntryPoint renders an "Access not granted" panel and the BFF returns accessible: false

Sign-in flow: privileged handoff#

apps/oshun/admin/src/app/handoff/page.tsx

• Visit /handoff — public path (no admin session required)
• Has admin session already — parseAdminSessionToken(adminToken) returns valid; redirect to returnTo ?? '/'
• No admin session — render <HandoffLauncher> with:
  • Eyebrow: "Oshun · Operations"
  • Heading: "Privileged handoff"
  • Body: explanation that admin cockpit is entered through explicit privileged handoff from consumer
  • hasCustomerSession flag (from OSHUN_CONSUMER_SESSION_COOKIE_NAME presence)
  • requestId (from x-request-id header) for support reference
• returnTo query param — sanitized via sanitizeReturnTo (verify the rules — likely path-only, no protocol/host)
• reason query param — surfaced for the operator to see why they hit handoff

The handoff itself is an out-of-band action (likely a back-channel admin login or a one-time link). The page describes the flow but the admin cookie is set by a separate endpoint (verify which).

Sign-out#

The admin app does not have a dedicated sign-out route in apps/oshun/admin/src/app. Sign-out is presumably handled by:

• Deleting OSHUN_ADMIN_SESSION_COOKIE_NAME via an API route (verify apps/oshun/admin/src/app/api/admin/*)
• OR a header action wired through the studio governance flow

Open question: where does the operator sign out from? Flag in matrix.

Session refresh#

The admin cookie is parsed on every request via parseAdminSessionToken. No refresh path is visible in session-cookie.ts — token rotation likely happens out-of-band on each privileged handoff. Open question: does the token expire?

Scopes and workspace access#

Each workspace declares requiredScopes in OSHUN_ADMIN_WORKSPACE_MODEL. Examples:

• dashboard — ['admin:*', 'admin:studio']
• inbox — ['admin:*', 'admin:studio']
• review — ['admin:*', 'admin:studio', 'admin:workspace:review']
• trust-safety — ['admin:*', 'admin:studio', 'admin:workspace:moderation']
• incidents — ['admin:*', 'admin:studio', 'admin:workspace:incident']
• personas — ['admin:*', 'admin:studio', 'admin:workspace:persona']
• models — ['admin:*', 'admin:studio', 'admin:workspace:model']
• editorial — ['admin:*', 'admin:studio', 'admin:workspace:editorial']
• research-integrity — ['admin:*', 'admin:studio', 'admin:workspace:research-integrity']
• rights — ['admin:*', 'admin:studio', 'admin:workspace:rights']
• support — ['admin:*', 'admin:studio', 'admin:workspace:support']
• privacy — ['admin:*', 'admin:studio', 'admin:workspace:privacy']
• policy — ['admin:*', 'admin:studio', 'admin:workspace:policy']
• lilith — ['admin:*', 'admin:studio', 'admin:workspace:lilith']

admin:* is the superuser scope; admin:studio is the broad studio-operator scope; workspace-specific scopes (admin:workspace:*) allow finer-grained delegation. canEnterAdminWorkspace(scopes, workspaceId) returns true if any of the workspace's requiredScopes is present.

Scopes test matrix#

The above is derived from how the requiredScopes arrays are written — verify with the canonical canEnterAdminWorkspace test suite at libs/oshun/navigation/src/admin-ia.test.ts.

Unauthorized page (/unauthorized)#

apps/oshun/admin/src/app/unauthorized/page.tsx

Three known reasons (from REASON_COPY):

• missing-session — "Admin session required" heading; body tells operator to use privileged handoff and that customer sessions cannot enter admin routes
• invalid-session — "Admin session expired or invalid" heading; body tells operator to request a new privileged handoff
• forbidden-workspace — "Workspace access denied" heading; body tells operator their role doesn't grant the workspace scope

returnTo query param is preserved so the operator can resume after handoff.

Cross-references#

• 02-routing-layouts.md — middleware that enforces the session
• 04-workspace-pattern.md — how individual pages enforce scope after middleware passes
• V1 PWA equivalent: ../../WALKTHROUGH/shell/04-auth-session.md
• Session cookie module: apps/oshun/admin/src/lib/session-cookie.ts
• Server session module: apps/oshun/admin/src/lib/server-session.ts

Open questions / known gaps#

• Document the upstream service that issues the admin session token after privileged handoff
• Confirm token expiry / refresh policy
• Locate the sign-out path (likely an /api/admin/* route)
• Verify sanitizeReturnTo rules in handoff/page.tsx
• Document how forbidden-workspace is triggered — middleware doesn't check scope, so this reason originates from a page or BFF