2d34aa15a7
Implements the GET /pass?token=... endpoint for validating session tokens, resolving the correct target application domain dynamically, and routing users seamlessly using ephemeral 1-click magic links. Also updates the Sessions Hub UI hand-off modal to display the 1-Click Magic Link and adds full test coverage. Co-authored-by: mrteye <1945243+mrteye@users.noreply.github.com>
247 lines
8.3 KiB
Markdown
247 lines
8.3 KiB
Markdown
# 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
|
|
```
|