Merge branch 'main' into feature/expiry-countdown

Author: ScriptedBro

.env.example

@@ -102,5 +102,15 @@ JWT_AUDIENCE=delego-clients
 # Helps tolerate minor clock drift between distributed services. Default 5, max 300.
 JWT_CLOCK_TOLERANCE_SECONDS=5
 
+# --- OAuth2 Providers ---
+# Google OAuth2 (https://console.cloud.google.com/apis/credentials)
+GOOGLE_CLIENT_ID=
+GOOGLE_CLIENT_SECRET=
+# GitHub OAuth (https://github.com/settings/developers)
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+# Redirect URI for OAuth callbacks (must match provider configuration)
+OAUTH_REDIRECT_URI=http://localhost:3000/api/v1/auth/oauth/callback
+
 # --- Analytics ---
 ANALYTICS_ENABLED=true

apps/backend/gateway/auth/README.md

@@ -2,11 +2,70 @@
 
 Authentication and authorization modules for the API gateway.
 
+## Features
+
+- Email/password authentication with JWT access + refresh tokens
+- OAuth2 login via Google and GitHub providers
+- Refresh token rotation with reuse detection
+- Audit event logging for all auth actions
+
+## OAuth2 Integration
+
+### Supported Providers
+
+| Provider | Authorization URL | Token URL | User Info URL |
+|----------|-------------------|-----------|---------------|
+| Google   | `https://accounts.google.com/o/oauth2/v2/auth` | `https://oauth2.googleapis.com/token` | `https://www.googleapis.com/oauth2/v3/userinfo` |
+| GitHub   | `https://github.com/login/oauth/authorize` | `https://github.com/login/oauth/access_token` | `https://api.github.com/user` |
+
+### Environment Variables
+
+```bash
+# Google OAuth2
+GOOGLE_CLIENT_ID=your-google-client-id
+GOOGLE_CLIENT_SECRET=your-google-client-secret
+
+# GitHub OAuth
+GITHUB_CLIENT_ID=your-github-client-id
+GITHUB_CLIENT_SECRET=your-github-client-secret
+
+# Redirect URI (must match provider configuration)
+OAUTH_REDIRECT_URI=http://localhost:3000/api/v1/auth/oauth/callback
+```
+
+### Endpoints
+
+- `GET /api/v1/auth/oauth/authorize?provider={google|github}&redirect_uri={uri}` - Returns authorization URL
+- `POST /api/v1/auth/oauth/callback` - Exchanges code for tokens and authenticates user
+
+### Account Linking
+
+When a user authenticates via OAuth:
+1. If an OAuth account link exists for the provider/userId, the existing user is authenticated
+2. If no link exists but a user with the same email is found, the OAuth account is linked to that user
+3. If neither exists, a new user is created (without a password) and the OAuth account is linked
+
+### Database Migration
+
+Run migration `013_oauth_providers.sql` to create the `oauth_accounts` table:
+
+```sql
+CREATE TABLE IF NOT EXISTS oauth_accounts (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  provider VARCHAR(32) NOT NULL,
+  provider_user_id VARCHAR(255) NOT NULL,
+  email VARCHAR(255),
+  display_name VARCHAR(255),
+  avatar_url TEXT,
+  created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+  UNIQUE(provider, provider_user_id)
+);
+```
+
 ## Planned
 
-- JWT validation
 - Wallet signature verification (Stellar)
 - Rate limiting per user
 - API key support for merchant integrations
-
-<!-- TODO: Implement auth providers -->

apps/backend/gateway/routes/api-v1.ts

@@ -37,6 +37,7 @@ export function getBodyLimitConfig(): BodyLimitConfig {
 }
 
 /** Parse a human-readable JSON body limit string into bytes. */
+
 export function parseJsonLimit(limit: string): number {
   const trimmed = limit.trim().toLowerCase();
   const match = trimmed.match(/^(\d+(?:\.\d+)?)(b|kb|mb|gb)?$/);

apps/backend/gateway/routes/auth.ts

@@ -1,6 +1,7 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { generateId, json } from "@delego/utils";
 import * as authService from "../src/auth/authService.js";
+import * as oauthService from "../src/auth/oauthService.js";
 import {
   publishAuthAuditEvent,
   AUTH_AUDIT_ACTIONS,
@@ -9,6 +10,7 @@ import {
   validateSchema,
   RegisterSchema,
   LoginSchema,
+  OAuthCallbackSchema,
 } from "../src/validation.js";
 import {
   readJsonBody,
@@ -27,6 +29,9 @@ export const authDependencies = {
   loginUser: authService.loginUser,
   refreshAccessToken: authService.refreshAccessToken,
   logoutUser: authService.logoutUser,
+  handleOAuthCallback: oauthService.handleOAuthCallback,
+  buildAuthorizationUrl: oauthService.buildAuthorizationUrl,
+  validateProvider: oauthService.validateProvider,
 };
 
 function resolveRequestId(req: IncomingMessage): string {
@@ -271,3 +276,86 @@ export async function logoutHandler(
     error: null,
   });
 }
+
+export async function oauthCallbackHandler(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  const requestId = resolveRequestId(req);
+
+  try {
+    const body = await readJsonBody(req);
+    const validation = validateSchema(OAuthCallbackSchema, body);
+    if (!validation.valid) {
+      publishAuthAuditEvent({
+        action: AUTH_AUDIT_ACTIONS.OAUTH_LOGIN,
+        success: false,
+        requestId,
+      });
+      badRequest(res, "Invalid request body", req, validation.errors);
+      return;
+    }
+
+    const { provider, code, state } = body;
+    const redirectUri = process.env.OAUTH_REDIRECT_URI ?? "";
+
+    const result = await authDependencies.handleOAuthCallback(provider, code, redirectUri);
+
+    publishAuthAuditEvent({
+      action: result.isNewUser ? AUTH_AUDIT_ACTIONS.OAUTH_REGISTER : AUTH_AUDIT_ACTIONS.OAUTH_LOGIN,
+      success: true,
+      requestId,
+      userId: result.user.id,
+      email: result.user.email,
+    });
+
+    setRefreshTokenCookie(res, result.refreshToken);
+    json(res, 200, {
+      data: {
+        user: result.user,
+        accessToken: result.accessToken,
+        expiresIn: result.expiresIn,
+        isNewUser: result.isNewUser,
+      },
+      error: null,
+    });
+  } catch (err: any) {
+    publishAuthAuditEvent({
+      action: AUTH_AUDIT_ACTIONS.OAUTH_LOGIN,
+      success: false,
+      requestId,
+    });
+    if (err instanceof InvalidJsonError || err instanceof BodyTooLargeError) {
+      badRequest(res, err.message, req);
+    } else {
+      sendApiError(res, 400, "OAUTH_ERROR", err.message, req);
+    }
+  }
+}
+
+export async function oauthAuthorizeHandler(
+  req: IncomingMessage,
+  res: ServerResponse,
+): Promise<void> {
+  const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+  const provider = url.searchParams.get("provider");
+  const redirectUri = url.searchParams.get("redirect_uri") ?? process.env.OAUTH_REDIRECT_URI ?? "";
+
+  if (!provider) {
+    sendApiError(res, 400, "VALIDATION_ERROR", "provider query parameter is required", req);
+    return;
+  }
+
+  try {
+    const validatedProvider = authDependencies.validateProvider(provider);
+    const state = generateId();
+    const authorizationUrl = authDependencies.buildAuthorizationUrl(validatedProvider, redirectUri, state);
+
+    json(res, 200, {
+      data: { authorizationUrl, state },
+      error: null,
+    });
+  } catch (err: any) {
+    sendApiError(res, 400, "INVALID_PROVIDER", err.message, req);
+  }
+}

apps/backend/gateway/routes/index.ts

@@ -7,6 +7,8 @@ import {
   loginHandler,
   refreshHandler,
   logoutHandler,
+  oauthCallbackHandler,
+  oauthAuthorizeHandler,
 } from "./auth.js";
 import {
   createDelegationHandler,
@@ -28,6 +30,8 @@ export function registerRoutes(): Route[] {
     route("POST", "/api/v1/auth/login", loginHandler),
     route("POST", "/api/v1/auth/refresh", refreshHandler),
     route("POST", "/api/v1/auth/logout", logoutHandler),
+    route("GET", "/api/v1/auth/oauth/authorize", oauthAuthorizeHandler),
+    route("POST", "/api/v1/auth/oauth/callback", oauthCallbackHandler),
     route("POST", "/api/v1/delegations", createDelegationHandler),
     route("GET", "/api/v1/delegations", listDelegationsHandler),
     route("GET", "/api/v1/delegations/:id", getDelegationHandler),

apps/backend/gateway/src/auth/authAuditEvent.ts

@@ -23,6 +23,8 @@ export const AUTH_AUDIT_ACTIONS = {
   REGISTER: "register",
   LOGOUT: "logout",
   REFRESH: "refresh",
+  OAUTH_LOGIN: "oauth_login",
+  OAUTH_REGISTER: "oauth_register",
 } as const;
 
 /** In-memory sink for auth audit events — swap for Redis publish in production. */