auth-yes/tasks/new/2026-0825.01.gem.feat.magic-passes.ephemeral-1-click-guest-links-0045.md

TASK METADATA

• Target Files:
  • server/main.ts
  • ui/components/SessionsPage.tsx
  • server/main.test.ts
• Core Objective: Implement GET /pass?token=... for 1-click ephemeral session redemption and update the Sessions Hub hand-off UI with copyable magic links.
• Dependencies: server/auth-session.ts, server/db.ts
• Additional Important Notes: Sets wildcard .atyg.org cookie, cleans host-only cookie, and redirects cleanly to target app domain or dashboard.

---

1. Architectural Considerations & Risks

• Security & Cookie Scoping:
  • /pass must validate that the token is active and not expired before issuing Set-Cookie headers.
  • Must use getCookieDomain() so subdomains (e.g. ed-droid.atyg.org) receive the session cookie immediately.
• Target URL Redirection:
  • If the session has custom scopes for an application (e.g. app:ed-droid), /pass looks up the domain of ed-droid and redirects directly to https://ed-droid.atyg.org.
  • If no specific app is scoped, redirects to /dashboard.

---

2. Proposed Implementation

1. Backend Route (server/main.ts):
   • Add GET /pass:
     • Reads c.req.query("token").
     • Validates token against Valkey/PostgreSQL.
     • Sets session_id cookie on .atyg.org.
     • Determines redirect URL and returns 302 Found.
2. UI Update (ui/components/SessionsPage.tsx):
   • Add "1-Click Magic Link" tab in #handoffModal.
   • Copyable link: https://auth.atyg.org/pass?token=ay_sess_....
3. Automated Tests (server/main.test.ts):
   • Add test case verifying token validation, cookie setting, and redirection.