# Ephemeral Magic Passes & Multi-Claim Event Passes Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use
> superpowers:subagent-driven-development (recommended) or
> superpowers:executing-plans to implement this plan task-by-task. Steps use
> checkbox (`- [ ]`) syntax for tracking.

**Goal:** Implement 1-on-1 Ephemeral Magic Links, Multi-Claim Event/Workshop
Passes (with short codes, PINs, short URLs, and CLI 1-liners), and a real-time
Event Cockpit with a master kill switch.

**Architecture:** Extend the Auth-Yes zero-trust session engine with a dedicated
event registry in PostgreSQL and Valkey. Provide a unified 1-click redemption
endpoint (`GET /pass`), a short-code/PIN join portal (`GET /join`,
`GET /e/:slug`), CLI environment streams (`GET /join/:slug?format=env`), and
live seat metrics with sub-millisecond batch revocation via Valkey RESP3 push
tracking.

**Tech Stack:** Deno 2.x, TypeScript 5.x, Hono SSR JSX (React-free), PostgreSQL
18, Valkey 8, Traefik ForwardAuth.

**Spec:**
[DUAL_AUDIENCE_DEVELOPMENT_GUIDE.md](../../DUAL_AUDIENCE_DEVELOPMENT_GUIDE.md)

## Global Constraints

- Strictly zero React dependencies; use pure Hono SSR JSX.
- Zero-dependency SDK in `sdk/`.
- All cookie mutations must delete host-only cookies and set wildcard
  `.atyg.org` domain cookies.
- Every commit and change must be pushed to both GitHub (`origin`) and Gitea
  (`gitea`).
- Quality gates must pass: `deno fmt`, `deno task lint`, `deno task check`,
  `deno task test`.

---

### Task 1: 1-on-1 Ephemeral Magic Link Redemption (`/pass`)

**Files:**

- Modify: `server/main.ts`
- Modify: `ui/components/SessionsPage.tsx`
- Test: `server/main.test.ts`

**Interfaces:**

- Consumes: `extractAllSessionIds(c)`, `valkey.get()`, `sqlWrapper.sql`
- Produces: `GET /pass?token=...` endpoint and updated Hand-Off Modal in
  `SessionsPage.tsx`

- [ ] **Step 1: Write the failing test for `GET /pass`**

```typescript
// in server/main.test.ts
Deno.test("GET /pass - Ephemeral Magic Link 1-Click Redemption", async (t) => {
  await t.step(
    "Valid token sets wildcard cookie and redirects to target app",
    async () => {
      const valkeyStub = stub(valkey, "get", (key: any) => {
        if (String(key) === "ay_sess_valid_pass") {
          return Promise.resolve(
            JSON.stringify({
              uuid: "guest-uuid",
              username: "guest_user",
              customScopes: ["app:ed-droid"],
            }),
          );
        }
        return Promise.resolve(null);
      });

      const originalSql = sqlWrapper.sql;
      sqlWrapper.sql = ((_query: any) => {
        return Promise.resolve([{ domain: "ed-droid.atyg.org" }]);
      }) as any;

      try {
        const res = await app.request("/pass?token=ay_sess_valid_pass", {
          method: "GET",
        });
        assertEquals(res.status, 302);
        const setCookie = res.headers.get("set-cookie") || "";
        assert(setCookie.includes("session_id=ay_sess_valid_pass"));
        assert(
          res.headers.get("location")?.includes("ed-droid.atyg.org") ||
            res.headers.get("location") === "/dashboard",
        );
      } finally {
        sqlWrapper.sql = originalSql;
        valkeyStub.restore();
      }
    },
  );
});
```

- [ ] **Step 2: Run test to verify it fails** Run:
      `deno test server/main.test.ts --filter "Ephemeral Magic Link"` Expected:
      FAIL (404 Not Found on `/pass`)

- [ ] **Step 3: Implement `GET /pass` in `server/main.ts`** Extract token from
      `?token=...`, validate against Valkey/DB, set cookie with
      `getCookieDomain()`, resolve target app domain if scoped to a specific
      app, and return `c.redirect(targetUrl)`.

- [ ] **Step 4: Update `ui/components/SessionsPage.tsx`** Add the **"1-Click
      Magic Link"** copy card tab alongside the CLI and cURL header tabs.

- [ ] **Step 5: Run tests to verify they pass** Run: `deno task test` Expected:
      PASS (All tests passing)

- [ ] **Step 6: Commit and Push**

```bash
git add server/main.ts server/main.test.ts ui/components/SessionsPage.tsx
git commit -m "feat(pass): implement 1-click ephemeral magic link redemption route"
git push origin main && git push gitea main
```

---

### Task 2: Multi-Claim Event Passes Schema & Join Endpoints (`/join`, `/e/:slug`, CLI 1-Liner)

**Files:**

- Modify: `server/db.ts`
- Modify: `server/main.ts`
- Create: `ui/components/EventJoinPage.tsx`
- Create: `ui/components/EventSplashPage.tsx`
- Test: `server/main.test.ts`

**Interfaces:**

- Produces:
  - Table: `event_passes` in PostgreSQL
  - Endpoints:
    - `POST /api/events`: Create event pass (slug, pin_code, name, max_seats,
      lifespan_hours, app_id, role)
    - `GET /e/:slug`: Web landing splash with "Enter Workshop" action
    - `GET /join`: Universal PIN / word-code entry page
    - `POST /api/join`: Redeems code/PIN and creates isolated
      `guest_<slug>_<index>` session
    - `GET /join/:slug`: CLI 1-liner (`?format=env` or `?format=json`)

- [ ] **Step 1: Write the failing tests for Event creation and redemption**

```typescript
Deno.test("Multi-Claim Event Passes & Join Endpoints", async (t) => {
  await t.step("POST /api/events creates an event pass", async () => {
    // Test event creation
  });
  await t.step("POST /api/join provisions an isolated guest seat", async () => {
    // Test seat provisioning
  });
  await t.step("GET /join/:slug?format=env returns shell export", async () => {
    // Test CLI 1-liner
  });
});
```

- [ ] **Step 2: Run test to verify it fails** Run:
      `deno test server/main.test.ts --filter "Multi-Claim Event"` Expected:
      FAIL

- [ ] **Step 3: Add `event_passes` schema in `server/db.ts`** Include columns:
      `id`, `slug`, `pin_code`, `name`, `app_id`, `role`, `max_seats`,
      `seats_claimed`, `lifespan_hours`, `created_by`, `is_active`,
      `expires_at`, `created_at`.

- [ ] **Step 4: Implement Event API routes in `server/main.ts` and SSR UI
      Pages**
- Create `ui/components/EventJoinPage.tsx` for `/join` PIN code entry.
- Create `ui/components/EventSplashPage.tsx` for `/e/:slug` 1-click workshop
  entrance.
- Implement `GET /join/:slug` returning `export AUTH_YES_TOKEN="..."` when
  `?format=env`.

- [ ] **Step 5: Run tests to verify they pass** Run: `deno task test` Expected:
      PASS

- [ ] **Step 6: Commit and Push**

```bash
git add server/db.ts server/main.ts ui/components/EventJoinPage.tsx ui/components/EventSplashPage.tsx server/main.test.ts
git commit -m "feat(events): implement multi-claim event passes, PIN join portal, and CLI 1-liner"
git push origin main && git push gitea main
```

---

### Task 3: Live Event Cockpit & Master Kill-Switch

**Files:**

- Modify: `server/main.ts`
- Modify: `ui/components/SessionsPage.tsx`
- Modify: `ui/mod.ts`
- Test: `server/main.test.ts`

**Interfaces:**

- Produces:
  - `POST /api/events/:id/end`: Closes event and immediately revokes all guest
    sessions
  - `POST /api/events/:id/extend`: Adds hours to active event
  - Event Management Deck in `SessionsPage.tsx` with live seat counter
    (`38 / 50`) and master kill switch

- [ ] **Step 1: Write failing tests for Event Kill-Switch & Extension**

```typescript
Deno.test("Event Cockpit & Master Kill Switch", async (t) => {
  await t.step(
    "POST /api/events/:id/end revokes all guest seats instantly",
    async () => {
      // verify sessions deleted and Valkey cleared
    },
  );
});
```

- [ ] **Step 2: Run test to verify it fails** Run:
      `deno test server/main.test.ts --filter "Event Cockpit"` Expected: FAIL

- [ ] **Step 3: Implement `POST /api/events/:id/end` and
      `POST /api/events/:id/extend` in `server/main.ts`** Fetch all session IDs
      created under the event pass, delete them from Valkey and PostgreSQL,
      record in audit ledger, and mark event `is_active = false`.

- [ ] **Step 4: Update `ui/components/SessionsPage.tsx` with Event Cockpit
      Deck** Display active events with live progress bar
      (`Seats Claimed / Capacity`), PIN badge, copy links, `[+1h Extend]` and
      `[🔴 End Workshop & Revoke All]`.

- [ ] **Step 5: Run full quality gates** Run:
      `deno fmt && deno task lint && deno task check && deno task test`
      Expected: All pass.

- [ ] **Step 6: Commit and Push**

```bash
git add server/main.ts ui/components/SessionsPage.tsx ui/mod.ts server/main.test.ts
git commit -m "feat(cockpit): add live event metrics, seat roster, and master kill-switch"
git push origin main && git push gitea main
```