Agent Directive: OAuth2 Authentication & Edge Authorisation

Objective

Implement a secure OAuth2 authentication flow using Microsoft Entra ID (Azure AD). The Astro PWA must authenticate users and attach Bearer tokens to requests. The Cloudflare Worker API must validate these JWTs at the edge and enforce scope-based authorisation before returning data.

Execution Sequence

1. Cloudflare Worker API (Edge Authorisation)

• Navigate to api/src/.
• Create a middleware function (e.g., auth.ts) that intercepts all requests to protected routes.
• The middleware must extract the Authorization: Bearer <token> header.
• Implement JWT validation. For local development, create a mock verification flow that accepts a valid test token, but structure it to use JWKS (JSON Web Key Set) verification for production Azure AD tokens.
• Enforce scope checking: Reject requests with 403 Forbidden if the token lacks required scopes (e.g., graph:read).

2. Astro PWA Frontend (User Authentication)

• Navigate to app/src/.
• Install the required Microsoft Authentication Library (MSAL) for the browser: npm install @azure/msal-browser --legacy-peer-deps.
• Create an authContext or utility library in app/src/lib/auth.ts to handle login, logout, and token acquisition.
• Update the frontend API fetch logic to automatically append the Bearer token to all outbound requests to /api/*.
• Create a "Login" button component in the UI that triggers the MSAL popup/redirect flow.

3. Environment Variables

• Update settings/.env.local to include placeholder variables for Azure AD: SKNX_ERO_CLIENT_ID and SKNX_ERO_TENANT_ID.

4. Update System Builder

• Read SYSTEM_BUILDER.md.
• Ensure docs/22-oauth-integration.md is listed in the Artefact Index.
• Mark this step as complete under "Phase 3: Security & Authentication".