Merge pull request #3 from foundersandcoders/feature/ap-14-magic-link-authentication

feat: implement magic link authentication

Author: AlexVOiceover

.env.example

@@ -3,4 +3,5 @@ AIRTABLE_BASE_ID=
 RESEND_API_KEY=
 DISCORD_WEBHOOK_URL=
 MAGIC_LINK_SECRET=
-SESSION_SECRET=
+SESSION_SECRET=
+AUTH_SECRET=

.gitignore

@@ -26,3 +26,4 @@ vite.config.ts.timestamp-*
 Assesment-criteria.md
 ksbs.md
 
+plan.md

README.md

@@ -14,14 +14,41 @@ Create a `.env.local` file with your Airtable credentials:
 AIRTABLE_API_KEY=your_api_key
 AIRTABLE_BASE_ID_LEARNERS=your_base_id
 AIRTABLE_BASE_ID_FEEDBACK=your_base_id
+AUTH_SECRET=your_auth_secret
 ```
 
+## Staff Access
+
+To grant someone staff access (for managing events):
+
+1. Add them as a **collaborator** in the Airtable workspace
+2. Add a record for them in the **Staff - Apprentice Pulse** table (`tblJjn62ExE1LVjmx`), selecting their collaborator profile in the Staff Name field
+
+Staff members can then log in using their collaborator email address.
+
 ## Development
 
 ```sh
 npm run dev
 ```
 
+## Testing Authentication (Development)
+
+Since magic links are logged to the console (not emailed) during development, follow these steps to test login:
+
+1. **Start the dev server** - `npm run dev`
+2. **Call the login endpoint** - Use Postman or curl:
+   ```sh
+   curl -X POST http://localhost:5173/api/auth/login \
+     -H "Content-Type: application/json" \
+     -d '{"email": "[email protected]"}'
+   ```
+3. **Copy the token** - Check the server terminal for the magic link URL containing the token
+4. **Visit verify in your browser** - Navigate to `http://localhost:5173/api/auth/verify?token=YOUR_TOKEN`
+5. **You're logged in** - The session cookie is set and you'll be redirected to `/`
+
+**Important:** The verify step must be done in the browser (not Postman) because the session cookie needs to be set in the browser where you're viewing the app.
+
 ## Scripts
 
 | Command | Description |

docs/planning/sprint02.png

@@ -2,11 +2,20 @@
 I created the boiler plate code, basic CI and deployment at the very beggining off the project (AP-3, AP-2, AP-8).
 The idea is to have as soon as possible a "Hello world". In this context that would be a deployed sveltkit app that can read and write a value on Airtable.
 
-# Testing from the very beginning
+# Testing Strategy
 
-I created a test script (`scripts/test-airtable.ts`) to verify read and write access to Airtable before building any features. This script uses dotenv to load credentials from `.env.local` and tests creating and reading records from a dedicated test table.
+We use Vitest for automated testing with a co-location pattern: test files (`.spec.ts`) live next to the source files they test. This makes tests easy to find and encourages test coverage.
 
-The project uses Vitest with Playwright for browser-based component testing, with Playwright browsers installed automatically via a postinstall hook. At the moment test is boilerplate, so we are not really testing any real functionality
+**Structure:**
+- `src/lib/**/*.spec.ts` - Unit tests for library code
+- `src/routes/**/*.spec.ts` - Component tests for pages
+
+**Manual integration scripts** live in `scripts/` and are used for verifying real API connectivity during development:
+- `scripts/check-airtable-connection.ts` - Verify Airtable read/write access
+- `scripts/check-cohort-apprentices.ts` - Test cohort lookup functionality
+- `scripts/fetch-schema.ts` - Fetch and document Airtable schema
+
+This separation keeps automated tests (fast, mocked, run in CI) distinct from manual integration checks (slow, real API, run during development). [P6 - 30%] [P7 - 30%]
 
 
 # Importing Airtable schema
@@ -70,5 +79,29 @@ During Sprint 02, I identified that certain tasks required permissions I did not
 
 This approach improved visibility into the project status and helped me prioritise effectively, focusing on tasks within my control while maintaining a clear follow-up list for delegated items. [P1 - 50%] [P2 - 40%] [K2, K6]
 
+# Authentication
+We use jsonwebtoken library to authenticate learners and staff. This allows us to:
+  * Generate the magic link token
+  * Verify the token
+
+**API testing:** We use Postman to manually test the authentication endpoints during development. This allows us to verify request/response payloads and debug the auth flow before building the frontend.
+
+## Role-based Access Control
+
+The `findUserByEmail` function implements role-based authentication by checking two Airtable tables:
+
+1. **Staff table** - Returns `type: 'staff'` for admin access
+2. **Apprentices table** - Returns `type: 'student'` for learner access
 
+A technical challenge arose with the Staff table: the email is stored in a `singleCollaborator` field (an Airtable collaborator object with `{ id, email, name }`). Unlike regular text fields, collaborator fields cannot be filtered using Airtable's `filterByFormula`. The solution was to fetch all staff records and iterate through them in code, comparing emails case-insensitively:
+
+```typescript
+for (const record of staffRecords) {
+	const collaborator = record.get(STAFF_FIELDS.COLLABORATOR);
+	if (collaborator?.email?.toLowerCase() === email.toLowerCase()) {
+		return { type: 'staff' };
+	}
+}
+```
 
+This approach ensures staff members can authenticate regardless of how their email is capitalised in Airtable. [K2 - 40%] [S5 - 30%] [D2 - 20%]

docs/report.md

@@ -170,6 +170,19 @@ Intervention and support request tracking.
 
 ---
 
+## Staff - Apprentice Pulse
+
+**Table ID:** `tblJjn62ExE1LVjmx`
+
+Staff members for authentication. Uses Airtable collaborators for email lookup.
+
+| Field | ID | Type | Purpose |
+|-------|-----|------|---------|
+| Id | `fldbTKP32s3Soev91` | autoNumber | Record ID |
+| Staff Name | `fldHEHhQInmSdipn8` | singleCollaborator | Collaborator with id, email, name |
+
+---
+
 ## Cohorts
 
 **Table ID:** `tbllAnSw8VPYFAa1a`