@eventmodelers/node-kit 0.0.11 → 0.0.12

package/templates/root/src/supabase/LoginHandler.ts

@@ -0,0 +1,36 @@
+import {type EmailOtpType} from '@supabase/supabase-js'
+import {Request, Response} from "express";
+
+import createClient from './api'
+
+function stringOrFirstString(item: string | string[] | undefined) {
+    return Array.isArray(item) ? item[0] : item
+}
+
+export default async function LoginHandler(req: Request, res: Response) {
+    if (req.method !== 'GET') {
+        res.status(405).appendHeader('Allow', 'GET').end()
+        return
+    }
+
+    const queryParams = req.query
+    const token_hash = stringOrFirstString(queryParams["token_hash"]?.toString())
+    const type = stringOrFirstString(queryParams["type"]?.toString())
+
+    let next = '/error'
+
+    if (token_hash && type) {
+        const supabase = createClient()
+        const {error} = await supabase.auth.verifyOtp({
+            type: type as EmailOtpType,
+            token_hash,
+        })
+        if (error) {
+            console.error(error)
+        } else {
+            next = stringOrFirstString(queryParams["next"]?.toString()) || '/'
+        }
+    }
+
+    res.redirect(next)
+}

package/templates/root/src/supabase/ProtectedPageProps.ts

@@ -0,0 +1,21 @@
+import {type Request, type Response} from "express";
+import {createClient} from "./serverProps";
+
+export async function getAuthenticatedUser(req: Request, res: Response) {
+    const supabase = createClient(req, res)
+    const {data, error} = await supabase.auth.getUser()
+    if (error || !data) {
+        return null
+    }
+    return data.user
+}
+
+export async function requireAuthMiddleware(req: Request, res: Response, next: () => void) {
+    const user = await getAuthenticatedUser(req, res)
+    if (!user) {
+        res.redirect('/auth/login')
+        return
+    }
+    (req as any).user = user
+    next()
+}

package/templates/root/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/root/src/supabase/api.ts

@@ -0,0 +1,56 @@
+import {createClient as createSupabaseClient} from '@supabase/supabase-js'
+import {Request} from 'express'
+
+let _serviceClient: ReturnType<typeof createSupabaseClient> | null = null;
+
+export const createServiceClient = () => {
+    if (!_serviceClient) {
+        _serviceClient = createSupabaseClient(
+            process.env.SUPABASE_URL!,
+            process.env.SUPABASE_SECRET_KEY!
+        );
+    }
+    return _serviceClient;
+}
+
+/**
+ * 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 ', '') || '';
+    return createSupabaseClient(
+        process.env.SUPABASE_URL!,
+        process.env.SUPABASE_PUBLISHABLE_KEY!,
+        {
+            auth: {
+                persistSession: false,
+                autoRefreshToken: false,
+                detectSessionInUrl: false,
+            },
+            global: {
+                headers: {
+                    Authorization: `Bearer ${token}`,
+                },
+            },
+        }
+    );
+}

package/templates/root/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/root/src/supabase/requireOrgaAdmin.ts

@@ -0,0 +1,32 @@
+import {Response} from 'express';
+import {SupabaseClient} from '@supabase/supabase-js';
+
+type RequireOrgaAdminResult = {
+    ok: true;
+    error: null;
+} | {
+    ok: false;
+    error: string;
+};
+
+export async function requireOrgaAdmin(
+    supabase: SupabaseClient,
+    orgaId: string,
+    userId: string,
+    res: Response,
+): Promise<RequireOrgaAdminResult> {
+    const {data, error} = await supabase
+        .from('user_organizations')
+        .select('role')
+        .eq('orga_id', orgaId)
+        .eq('user_id', userId)
+        .eq('role', 'admin')
+        .single();
+
+    if (error || !data) {
+        res.status(403).json({error: 'Forbidden: admin role required'});
+        return {ok: false, error: 'FORBIDDEN'};
+    }
+
+    return {ok: true, error: null};
+}

package/templates/root/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/root/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/root/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/root/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/root/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!!;
+}

package/templates/root/src/util/hash.ts

@@ -0,0 +1,9 @@
+// Fast djb2-style hash of any object — used to detect drift
+export function hashMeta(entry: unknown): string {
+    const str = JSON.stringify(entry);
+    let h = 5381;
+    for (let i = 0; i < str.length; i++) {
+        h = (((h << 5) + h) ^ str.charCodeAt(i)) >>> 0;
+    }
+    return h.toString(36);
+}

package/templates/root/src/util/sanitize.ts

@@ -0,0 +1,23 @@
+function sanitizeValue(value: unknown): unknown {
+    if (typeof value === 'bigint') {
+        return Number.isSafeInteger(Number(value)) ? Number(value) : value.toString();
+    }
+    if (Array.isArray(value)) {
+        return value.map(sanitizeValue);
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(
+            Object.entries(value).map(([k, v]) => [k, sanitizeValue(v)])
+        );
+    }
+    return value;
+}
+
+export function sanitize<T>(value: T): unknown {
+    return sanitizeValue(value);
+}
+
+export const jsonBigIntReplacer = (_key: string, value: unknown): unknown =>
+    typeof value === 'bigint'
+        ? (Number.isSafeInteger(Number(value)) ? Number(value) : value.toString())
+        : value;