@nebulit/embuilder 0.1.39

package/templates/backend/src/supabase/README.md

@@ -0,0 +1,171 @@
+# Supabase JWT Authentication for Backend API
+
+This backend API uses Supabase JWT tokens for authentication. Clients must include a valid JWT token in the
+`Authorization` header.
+
+## Quick Start
+
+1. **Set up environment variables** in `.env.local`:
+   ```env
+   NEXT_PUBLIC_SUPABASE_URL=http://127.0.0.1:54321
+   NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here
+   ```
+
+2. **Start the server**: `npm run dev`
+
+3. **Get a test JWT token**:
+    - Visit http://localhost:3000/auth/login
+    - Create an account or login
+    - Copy the JWT token displayed
+    - Use it in your API requests
+
+## Test Login Page
+
+A simple test login page is available at `/auth/login` that:
+
+- Allows you to create accounts or login
+- Displays the JWT token after authentication
+- Provides a "Test API Call" button
+- Shows a cURL example for testing
+
+This page is for testing purposes only.
+
+## How It Works
+
+1. **Client obtains JWT token** from Supabase (via your frontend app)
+2. **Client sends requests** with `Authorization: Bearer <jwt-token>` header
+3. **Backend verifies JWT** using Supabase and extracts user info
+4. **Protected routes** return user data or 401 Unauthorized
+
+## Usage Examples
+
+### Option 1: Using `requireUser` function
+
+```typescript
+import {requireUser} from './src/supabase/requireUser';
+import {Request, Response} from 'express';
+
+app.get('/api/protected', async (req: Request, res: Response) => {
+    const result = await requireUser(req, res, false);
+
+    if (result.error) {
+        return res.status(401).json({error: result.error});
+    }
+
+    const user = result.user;
+    res.json({
+        message: 'Protected data',
+        userId: user.id,
+        email: user.email
+    });
+});
+```
+
+### Option 2: Using `authMiddleware`
+
+```typescript
+import {authMiddleware} from './src/supabase/authMiddleware';
+
+app.get('/api/protected', authMiddleware, (req, res) => {
+    // User is available on req.user after middleware
+    const user = (req as any).user;
+
+    res.json({
+        message: 'Protected data',
+        user: user
+    });
+});
+```
+
+### Testing with curl
+
+```bash
+# Get JWT token from your Supabase client first
+TOKEN="your-jwt-token-here"
+
+# Test protected endpoint
+curl -H "Authorization: Bearer $TOKEN" http://localhost:3000/api/user
+
+# Expected response:
+# {
+#   "userId": "...",
+#   "email": "user@example.com",
+#   "metadata": { ... }
+# }
+```
+
+### Testing with JavaScript fetch
+
+```javascript
+const token = supabase.auth.session()?.access_token;
+
+fetch('http://localhost:3000/api/user', {
+    headers: {
+        'Authorization': `Bearer ${token}`
+    }
+})
+    .then(res => res.json())
+    .then(data => console.log(data));
+```
+
+## API Endpoints
+
+### `GET /api/user`
+
+Returns current authenticated user information.
+
+**Headers:**
+
+- `Authorization: Bearer <jwt-token>` (required)
+
+**Success Response (200):**
+
+```json
+{
+    "userId": "uuid",
+    "email": "user@example.com",
+    "metadata": { ... }
+}
+```
+
+**Error Responses:**
+
+- `401 Unauthorized`: Missing or invalid token
+- `500 Internal Server Error`: Server error
+
+## Files
+
+- **`api.ts`**: Supabase client creation
+- **`requireUser.ts`**: JWT verification function
+- **`authMiddleware.ts`**: Express middleware for protecting routes
+- **`README.md`**: This documentation
+
+## Architecture
+
+```
+Client Request
+    |
+    v
+Authorization: Bearer <JWT>
+    |
+    v
+Express Route
+    |
+    v
+requireUser() / authMiddleware
+    |
+    v
+Supabase JWT Verification
+    |
+    +---> Valid: Continue with user data
+    |
+    +---> Invalid: Return 401 Unauthorized
+```
+
+## Security Notes
+
+- JWT tokens are verified with Supabase on every request
+- No session storage on the backend (stateless)
+- Tokens expire based on Supabase configuration
+- Always use HTTPS in production
+- Store the anon key securely (use environment variables)

package/templates/backend/src/supabase/api.ts

@@ -0,0 +1,63 @@
+import {createClient as createSupabaseClient} from '@supabase/supabase-js'
+import {Request} from 'express'
+
+/**
+ * Creates a Supabase client for server-side API operations
+ * This client does not persist sessions and is used for JWT verification
+ */
+export const createServiceClient = () => {
+    console.log(process.env.SUPABASE_URL)
+    return createSupabaseClient(
+        process.env.SUPABASE_URL!,
+        process.env.SUPABASE_SECRET_KEY!
+    )
+}
+
+/**
+ * Creates a Supabase client for verifying JWT tokens
+ * Used in backend API endpoints
+ */
+export default function createClient() {
+    return createSupabaseClient(
+        process.env.SUPABASE_URL!,
+        process.env.SUPABASE_PUBLISHABLE_KEY!,
+        {
+            auth: {
+                persistSession: false,
+                autoRefreshToken: false,
+                detectSessionInUrl: false,
+            },
+        }
+    )
+}
+
+/**
+ * Creates an authenticated Supabase client with the user's JWT token
+ * This ensures Row Level Security (RLS) policies are applied with the user's context
+ */
+export async function createAuthenticatedClient(req: Request) {
+    const token = req.headers.authorization?.replace('Bearer ', '') || '';
+
+    console.log(token)
+    console.log(process.env.SUPABASE_URL!)
+    const client = createSupabaseClient(
+        process.env.SUPABASE_URL!,
+        process.env.SUPABASE_PUBLISHABLE_KEY!,
+        {
+            auth: {
+                persistSession: false,
+                autoRefreshToken: false,
+                detectSessionInUrl: false,
+            },
+        }
+    );
+
+    if (token) {
+        await client.auth.setSession({
+            access_token: token,
+            refresh_token: '',
+        });
+    }
+
+    return client;
+}

package/templates/backend/src/supabase/authMiddleware.ts

@@ -0,0 +1,53 @@
+import {NextFunction, Request, Response} from 'express';
+import {requireUser} from './requireUser';
+
+/**
+ * Express middleware to protect routes with JWT authentication
+ * Verifies the JWT token from Authorization header and attaches user to request
+ *
+ * Usage:
+ * ```typescript
+ * import {authMiddleware} from './src/supabase/authMiddleware';
+ *
+ * app.get('/api/protected', authMiddleware, (req, res) => {
+ *     const user = req.user; // TypeScript: use custom type definition
+ *     res.json({ message: 'Protected data', user });
+ * });
+ * ```
+ */
+export async function authMiddleware(req: Request, res: Response, next: NextFunction) {
+    try {
+        const result = await requireUser(req, res, false);
+
+        if (result.error) {
+            return res.status(401).json({
+                error: 'Unauthorized',
+                message: result.error
+            });
+        }
+
+        // Attach user to request for downstream handlers
+        (req as any).user = result.user;
+
+        next();
+    } catch (error) {
+        console.error('Auth middleware error:', error);
+        return res.status(500).json({
+            error: 'Internal server error',
+            message: 'Authentication failed'
+        });
+    }
+}
+
+/**
+ * TypeScript declaration to extend Express Request type
+ * Add this to your types file or use it directly:
+ *
+ * declare global {
+ *     namespace Express {
+ *         interface Request {
+ *             user?: any; // Or use your User type
+ *         }
+ *     }
+ * }
+ */

package/templates/backend/src/supabase/component.ts

@@ -0,0 +1,12 @@
+import {createBrowserClient} from '@supabase/ssr'
+
+/**
+ * Creates a Supabase client for browser/client-side operations
+ * Used in React components for authentication flows
+ */
+export function createClient() {
+    return createBrowserClient(
+        process.env.NEXT_PUBLIC_SUPABASE_URL!,
+        process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+    )
+}

package/templates/backend/src/supabase/requireUser.ts

@@ -0,0 +1,72 @@
+import {createAuthenticatedClient} from "./api";
+import {Request, Response} from "express"
+
+type RequireUserResult = {
+    user: any;
+    error: null;
+} | {
+    user: null;
+    error: string;
+};
+
+/**
+ * Extracts JWT token from Authorization header
+ * Supports "Bearer <token>" format
+ */
+function extractTokenFromHeader(req: Request): string | null {
+    const authHeader = req.headers.authorization;
+
+    if (!authHeader) {
+        return null;
+    }
+
+    // Check for "Bearer <token>" format
+    const parts = authHeader.split(' ');
+    if (parts.length === 2 && parts[0].toLowerCase() === 'bearer') {
+        return parts[1];
+    }
+
+    // If no Bearer prefix, assume the entire header is the token
+    return authHeader;
+}
+
+/**
+ * Verifies JWT token from Authorization header and returns user info
+ * This is for backend API use - does not use cookies or redirects
+ */
+export async function requireUser(req: Request, resp: Response, sendUnauthorized: boolean = true): Promise<RequireUserResult> {
+    const token = extractTokenFromHeader(req);
+
+    if (!token) {
+        if (sendUnauthorized) {
+            resp.status(401).json({error: 'Missing authorization token'});
+        }
+        return {
+            user: null,
+            error: 'MISSING_TOKEN',
+        };
+    }
+
+    const supabase = await createAuthenticatedClient(req);
+
+    // Verify the JWT token
+    const {
+        data: {user},
+        error
+    } = await supabase.auth.getUser(token);
+
+    if (error || !user) {
+        if (sendUnauthorized) {
+            resp.status(401).json({error: 'Invalid or expired token'});
+        }
+        return {
+            user: null,
+            error: error?.message || 'UNAUTHORIZED',
+        };
+    }
+
+    return {
+        user: user,
+        error: null
+    }
+}

package/templates/backend/src/supabase/serverProps.ts

@@ -0,0 +1,25 @@
+import {type Request, type Response} from 'express'
+import {createServerClient, serializeCookieHeader} from '@supabase/ssr'
+
+export function createClient(req: Request, res: Response) {
+    const supabase = createServerClient(
+        process.env.NEXT_PUBLIC_SUPABASE_URL!,
+        process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
+        {
+            cookies: {
+                getAll() {
+                    return Object.keys(req.cookies).map((name) => ({name, value: req.cookies[name] || ''}))
+                },
+                setAll(cookiesToSet: any[]) {
+                    res.setHeader(
+                        'Set-Cookie',
+                        cookiesToSet.map(({name, value, options}: any) =>
+                            serializeCookieHeader(name, value, options)
+                        )
+                    )
+                },
+            },
+        }
+    )
+    return supabase
+}

package/templates/backend/src/supabase/staticProps.ts

@@ -0,0 +1,10 @@
+import {createClient as createClientPrimitive} from '@supabase/supabase-js'
+
+export function createClient() {
+    const supabase = createClientPrimitive(
+        process.env.NEXT_PUBLIC_SUPABASE_URL!,
+        process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+    )
+
+    return supabase
+}

package/templates/backend/src/swagger.ts

@@ -0,0 +1,34 @@
+import swaggerJsdoc from 'swagger-jsdoc';
+
+const options = {
+    definition: {
+        openapi: '3.0.0',
+        info: {
+            title: 'Context API',
+            version: '1.0.0',
+            description: 'Event-driven API for shift, clerk, and task management',
+        },
+        servers: [
+            {
+                url: 'http://localhost:3000',
+                description: 'Development server',
+            },
+            {
+                url: process.env.API_URL || 'http://localhost:3000',
+                description: 'Production server',
+            },
+        ],
+        components: {
+            securitySchemes: {
+                bearerAuth: {
+                    type: 'http',
+                    scheme: 'bearer',
+                    bearerFormat: 'JWT',
+                },
+            },
+        },
+    },
+    apis: ['./src/slices/**/routes.ts'],
+};
+
+export const specs = swaggerJsdoc(options);

package/templates/backend/src/util/assertions.ts

@@ -0,0 +1,6 @@
+export function assertNotEmpty<T>(value: T): NonNullable<T> {
+    if (value === null || value === undefined) {
+        throw new Error("Expected non-empty value");
+    }
+    return value!!;
+}