Add “Continue as Guest” UX, Token Handling, and Upgrade Flow

[cubap]

Summary

Add a Guest Mode to the TPEN-Interfaces (plain JS/HTML/CSS) that:

• Lets users start as guest and obtain a temporary idToken from TPEN-Services.
• Uses that token to perform authenticated-like actions in the UI (save transcription, annotate, comment).
• Presents clear limits and a non-intrusive upgrade path (create auth0 user and migrate contributions to them).
• Ensures continuity via refresh token (cookie) and handles token rotation.

UX Requirements

• Entry Points:
  • “Continue as Guest” CTA on the editor or first write attempt.
  • Explain constraints: “Guest work may be temporary (2 days of inactivity). Upgrade within 30 days to keep it.”
• Badging & Status:
  • Show “Guest” badge in navbar/profile menu with display name, some clearly generated pseudo Latin or Greek author name.
  • Tooltip or small info panel with limits (rate, quotas, retention).
• Nudges (Soft Prompts):
  • After N actions (configurable), prompt: “Save work across devices—add email (no password).”
  • Before share/export: prompt upgrade (if policy requires).
• Upgrade Flow:
  • Magic link modal: collect email → call /guest/claim → show “Check your email.”
  • On claim-complete redirect, call /guest/upgrade → swap to user session; update UI.
  • Alternate: “Sign in with SSO” button that initiates OIDC flow.
• Export:
  • Allow guests to export their current transcription/annotation data as JSON (and/or CSV) without upgrading.

Frontend Architecture (Plain JS)

• Token Store:
  • Keep idToken in memory (JS variable).
  • Store refresh token in secure HttpOnly cookie (via services response).
  • Implement auto-refresh before idToken expiry; handle rotation & failure gracefully.
• API Client:
  • A small wrapper that attaches Authorization: Bearer <idToken> to write endpoints.
  • On 401 with “token expired”, trigger refresh; if refresh fails, prompt re-start guest or sign in.
• State & UI:
  • authState = { role: 'guest' | 'user', sub, displayName }.
  • Render conditional UI for guest capabilities and limits.

UI Copy (Suggested)

• Button: Continue as Guest
• Banner: “You’re in Guest Mode. Your work is saved to this device and may expire after 90 days. Upgrade to keep it across devices.”
• Nudge: “Add email to keep your progress.”
• Upgrade Modal:
  • Title: “Upgrade your Guest Account”
  • Subtext: “We’ll send you a one-click link. No password needed.”
  • Field: Email
  • CTA: Send Magic Link
• Success: “Check your email—click the link to finish.”
• Post-upgrade: “All your work has been moved to your account.”

API Integrations

• Start Guest: POST /guest/start → receive idToken, refreshToken, displayName, policy.
• Refresh: POST /auth/refresh (automatic before expiry).
• Write Ops: existing endpoints (transcriptions, annotations, comments) with guest idToken.
• Claim/Upgrade: POST /guest/claim (email); POST /guest/upgrade on redirect.

Error Handling

• Show clear messages on:
  • Project policy denial (allowGuestEdits=false): “This project does not allow guest edits. Sign in to continue.”
  • Quota exceeded: “Guest quota reached. Upgrade to continue editing.”
  • Rate limit triggered: “Too many actions. Please wait a moment.”
  • Refresh failure: “Session expired. Continue as Guest or Sign in.”

Accessibility & i18n

• Keep guest badge and prompts accessible (ARIA).
• Prepare strings for translation; avoid hard-coded English.

---

Tasks (Checklist)

• Add “Continue as Guest” button and entry UX.
• Implement start-guest call (/guest/start) and token storage logic.
• Implement auto-refresh flow (pre-expiry) with cookie-based refresh.
• Add guest badge and info panel with limits/retention messaging.
• Gate UI actions based on role=guest vs role=user and project policy responses.
• Implement upgrade modal (email input) → call /guest/claim.
• Handle claim-complete redirect → call /guest/upgrade → update session/UI.
• Add export for guest data (JSON/CSV, depending on current features).
• Add error/limit banners and retry affordances.
• Telemetry: track guest session starts, write volumes, upgrade conversions.
• Update README/help docs with Guest Mode explanation.

Acceptance Criteria

• Users can enter Guest Mode and perform allowed actions.
• Token rotation works seamlessly; the UI stays authenticated as guest.
• Project policy denials are surfaced clearly; allowed actions function normally.
• Upgrade via magic link flows correctly and preserves the user’s work.
• Export works for guests without requiring upgrade.
• Strings and UI are accessible and translatable (where applicable).
• Documentation and help content updated.

Open Questions

• Exact copy for retention.
• Which endpoints are blocked for guests (invite/share/private project settings)?