docs(design): add OKF user story catalog

2026-08-01 14:49:37 -04:00
parent 2657399628
commit fa5346458a
21 changed files with 777 additions and 1 deletions
@@ -0,0 +1,39 @@
+---
+type: User Story
+title: Authenticate with a Discord magic link
+description: Discord users receive private single-use links that establish secure portal sessions.
+tags: [player, discord, authentication, security]
+timestamp: 2026-08-01T18:43:58Z
+story_id: US-002
+status: verified
+---
+
+# User Story
+
+As a Discord community member, I want `/register` and `/account` to issue a private sign-in link, so that I can access the portal without creating another password.
+
+# Acceptance Criteria
+
+- [x] Given the configured guild, when a user runs `/register` or `/account`, then the bot responds ephemerally with a private link.
+- [x] Given a generated link, then the raw login token is never stored in PostgreSQL.
+- [x] Given a login token, then it expires after ten minutes and can be consumed only once.
+- [x] Given repeated link requests, then requests are rate limited per Discord user and older active links are invalidated.
+- [x] Given a valid link, when it is consumed, then the Discord user is created or refreshed and a secure seven-day session is established.
+- [x] Given an invalid, expired, or consumed link, then the user sees a safe recovery page instructing them to request another link.
+
+# Implementation
+
+- [`apps/discord-bot/src/index.ts`](../apps/discord-bot/src/index.ts)
+- [`packages/auth/src/index.ts`](../packages/auth/src/index.ts)
+- [`packages/database/src/auth-repository.ts`](../packages/database/src/auth-repository.ts)
+- [`apps/web/src/app/auth/discord/route.ts`](../apps/web/src/app/auth/discord/route.ts)
+
+# Validation
+
+- [`packages/auth/test/magic-link.test.ts`](../packages/auth/test/magic-link.test.ts)
+- Discord command and authentication workspaces pass TypeScript validation.
+
+# Related Stories
+
+- [Enter through Discord](us-001-discord-entry.md)
+- [Preserve an audit trail](us-010-audit-events.md)