insforge 0.3.1

package/backend/src/types/profile.ts

@@ -0,0 +1,55 @@
+// User and profile related type definitions
+
+import { AuthRecord, IdentifiesRecord } from './auth.js';
+
+// User profile metadata
+export interface UserMetadata {
+  status?: 'active' | 'inactive' | 'suspended';
+  preferences?: {
+    theme?: 'light' | 'dark';
+    language?: string;
+    notifications?: boolean;
+  };
+  settings?: {
+    [key: string]: string | number | boolean;
+  };
+  custom?: {
+    [key: string]: string | number | boolean | null;
+  };
+}
+
+// Profile database record
+export interface ProfileRecord {
+  id: string;
+  auth_id: string;
+  name: string;
+  avatar_url?: string;
+  bio?: string;
+  metadata?: UserMetadata;
+  created_at: string;
+  updated_at: string;
+}
+
+// Combined user with profile and identities
+export interface UserWithProfile extends AuthRecord {
+  profile: ProfileRecord;
+  identities: IdentifiesRecord[];
+}
+
+// Request to create a new user
+export interface CreateUserRequest {
+  email: string;
+  password: string;
+  name: string;
+  avatar_url?: string;
+  bio?: string;
+  metadata?: UserMetadata;
+}
+
+// Request to update profile
+export interface UpdateProfileRequest {
+  name?: string;
+  avatar_url?: string;
+  bio?: string;
+  metadata?: UserMetadata;
+}

package/backend/src/types/storage.ts

@@ -0,0 +1,23 @@
+// Storage-related type definitions
+import { StorageBucketSchema } from '@insforge/shared-schemas';
+
+// Base storage record from database
+export interface StorageRecord {
+  key: string;
+  bucket: string;
+  size: number;
+  mime_type?: string;
+  uploaded_at: string;
+}
+
+// Bucket record from _storage_buckets table
+export type BucketRecord = Omit<StorageBucketSchema, 'created_at'>;
+
+// Form field types for file uploads
+export type FormFieldValue = string | string[] | undefined;
+
+// Processed form data from multipart requests
+export interface ProcessedFormData {
+  fields: Record<string, FormFieldValue>;
+  files: Record<string, Express.Multer.File[]>;
+}

package/backend/src/utils/cloud-token.ts

@@ -0,0 +1,39 @@
+import { createRemoteJWKSet, JWTPayload, jwtVerify } from 'jose';
+import { AppError } from '@/api/middleware/error.js';
+import { ERROR_CODES, NEXT_ACTION } from '@/types/error-constants.js';
+
+/**
+ * Helper function to verify cloud backend JWT token
+ * Validates JWT tokens from api.insforge.dev using JWKS
+ */
+export async function verifyCloudToken(
+  token: string
+): Promise<{ projectId: string; payload: JWTPayload }> {
+  // Create JWKS endpoint for remote key set
+  const JWKS = createRemoteJWKSet(
+    new URL((process.env.CLOUD_API_HOST || 'https://api.insforge.dev') + '/.well-known/jwks.json')
+  );
+
+  // Verify the token with jose
+  const { payload } = await jwtVerify(token, JWKS, {
+    algorithms: ['RS256', 'RS384', 'RS512', 'ES256', 'ES384', 'ES512'],
+  });
+
+  // Verify project_id matches if configured
+  const tokenProjectId = payload['projectId'] as string;
+  const expectedProjectId = process.env.PROJECT_ID;
+
+  if (expectedProjectId && tokenProjectId !== expectedProjectId) {
+    throw new AppError(
+      'Project ID mismatch',
+      403,
+      ERROR_CODES.AUTH_UNAUTHORIZED,
+      NEXT_ACTION.CHECK_TOKEN
+    );
+  }
+
+  return {
+    projectId: tokenProjectId || expectedProjectId || 'local',
+    payload,
+  };
+}

package/backend/src/utils/constants.ts

@@ -0,0 +1 @@
+export const ADMIN_ID = '00000000-0000-0000-0000-000000000001';

package/backend/src/utils/environment.ts

@@ -0,0 +1,35 @@
+/**
+ * Environment utility functions for checking runtime environment
+ */
+
+/**
+ * Check if the application is running in a cloud environment
+ * Currently checks for AWS instance profile, but can be extended for other cloud providers
+ */
+export function isCloudEnvironment(): boolean {
+  return !!(
+    process.env.AWS_INSTANCE_PROFILE_NAME && process.env.AWS_INSTANCE_PROFILE_NAME.trim().length > 0
+  );
+}
+
+/**
+ * Check if the application can use shared OAuth keys
+ * This is typically enabled in cloud environments to avoid storing secrets
+ */
+export function isOAuthSharedKeysAvailable(): boolean {
+  return isCloudEnvironment();
+}
+
+/**
+ * Check if running in development mode
+ */
+export function isDevelopment(): boolean {
+  return process.env.NODE_ENV === 'development' || !process.env.NODE_ENV;
+}
+
+/**
+ * Check if running in production mode
+ */
+export function isProduction(): boolean {
+  return process.env.NODE_ENV === 'production';
+}

package/backend/src/utils/helpers.ts

@@ -0,0 +1,49 @@
+import { ColumnType } from '@insforge/shared-schemas';
+
+export const convertSqlTypeToColumnType = (sqlType: string): ColumnType | string => {
+  switch (sqlType.toLowerCase()) {
+    case 'uuid':
+      return ColumnType.UUID;
+    case 'timestamptz':
+    case 'timestamp with time zone':
+      return ColumnType.DATETIME;
+    case 'date':
+      return ColumnType.DATE;
+    case 'integer':
+    case 'bigint':
+    case 'smallint':
+    case 'int':
+    case 'int2':
+    case 'int4':
+    case 'serial':
+    case 'serial2':
+    case 'serial4':
+    case 'serial8':
+    case 'smallserial':
+    case 'bigserial':
+      return ColumnType.INTEGER;
+    case 'double precision':
+    case 'real':
+    case 'numeric':
+    case 'float':
+    case 'float4':
+    case 'float8':
+    case 'decimal':
+      return ColumnType.FLOAT;
+    case 'boolean':
+    case 'bool':
+      return ColumnType.BOOLEAN;
+    case 'json':
+    case 'jsonb':
+    case 'array':
+      return ColumnType.JSON;
+    case 'text':
+    case 'varchar':
+    case 'char':
+    case 'character varying':
+    case 'character':
+      return ColumnType.STRING;
+    default:
+      return sqlType.slice(0, 5);
+  }
+};

package/backend/src/utils/logger.ts

@@ -0,0 +1,13 @@
+import winston from 'winston';
+
+const logger = winston.createLogger({
+  level: process.env.LOG_LEVEL || 'info',
+  format: winston.format.combine(
+    winston.format.timestamp(),
+    winston.format.errors({ stack: true }),
+    winston.format.json()
+  ),
+  transports: [new winston.transports.Console()],
+});
+
+export default logger;

package/backend/src/utils/response.ts

@@ -0,0 +1,62 @@
+import { Response } from 'express';
+
+// Traditional REST response - data returned directly
+// Error responses use standard HTTP status codes with error body
+
+export interface ErrorResponse {
+  error: string;
+  message: string;
+  statusCode: number;
+  nextActions?: string;
+}
+
+export interface PaginationMeta {
+  total: number;
+  limit: number;
+  offset: number;
+  page?: number;
+  totalPages?: number;
+}
+
+// Traditional REST success response - returns data directly
+export function successResponse<T>(res: Response, data: T, statusCode: number = 200) {
+  return res.status(statusCode).json(data);
+}
+
+// Traditional REST error response
+export function errorResponse(
+  res: Response,
+  error: string,
+  message: string,
+  statusCode: number = 500,
+  nextActions?: string
+) {
+  const response: ErrorResponse = {
+    error,
+    message,
+    statusCode,
+    nextActions,
+  };
+
+  return res.status(statusCode).json(response);
+}
+
+// Pagination response helper - returns data with PostgREST-style pagination headers
+export function paginatedResponse<T>(res: Response, data: T[], total: number, offset: number) {
+  // Calculate the range for Content-Range header
+  const start = offset;
+  const end = Math.min(offset + data.length - 1, total - 1);
+
+  // Set PostgREST-style pagination headers
+  // Format: "Content-Range: start-end/total"
+  // Example: "Content-Range: 0-9/200" for first 10 items out of 200
+  res.setHeader('Content-Range', `${start}-${end}/${total}`);
+
+  // Also set Prefer header to indicate preference was applied
+  res.setHeader('Preference-Applied', 'count=exact');
+
+  // Use 206 Partial Content when not returning all results, 200 when returning everything
+  const statusCode = data.length < total ? 206 : 200;
+
+  return res.status(statusCode).json(data);
+}

package/backend/src/utils/seed.ts

@@ -0,0 +1,205 @@
+import { DatabaseManager } from '@/core/database/manager.js';
+import { AIConfigService } from '@/core/ai/config.js';
+import { isCloudEnvironment } from '@/utils/environment.js';
+import logger from '@/utils/logger.js';
+import { SecretsService } from '@/core/secrets/secrets';
+import { OAuthConfigService } from '@/core/auth/oauth.js';
+
+/**
+ * Validates admin credentials are configured
+ * Admin is authenticated via environment variables, not stored in DB
+ */
+function ensureFirstAdmin(adminEmail: string, adminPassword: string): void {
+  if (adminEmail && adminPassword) {
+    logger.info(`✅ Admin configured: ${adminEmail}`);
+  } else {
+    logger.warn('⚠️ Admin credentials not configured - check ADMIN_EMAIL and ADMIN_PASSWORD');
+  }
+}
+
+/**
+ * Seeds default AI configurations for cloud environments
+ */
+async function seedDefaultAIConfigs(): Promise<void> {
+  // Only seed default AI configs in cloud environment
+  if (!isCloudEnvironment()) {
+    return;
+  }
+
+  const aiConfigService = new AIConfigService();
+
+  // Check if AI configs already exist
+  const existingConfigs = await aiConfigService.findAll();
+
+  if (existingConfigs.length > 0) {
+    return;
+  }
+
+  await aiConfigService.create(
+    ['text', 'image'],
+    ['text'],
+    'openrouter',
+    'openai/gpt-4o',
+    'You are a helpful assistant.'
+  );
+
+  await aiConfigService.create(
+    ['text', 'image'],
+    ['text', 'image'],
+    'openrouter',
+    'google/gemini-2.5-flash-image-preview'
+  );
+
+  logger.info('✅ Default AI models configured (cloud environment)');
+}
+
+/**
+ * Seeds default OAuth configurations for Google and GitHub
+ */
+async function seedDefaultOAuthConfigs(): Promise<void> {
+  const oauthService = OAuthConfigService.getInstance();
+
+  try {
+    // Check if OAuth configs already exist
+    const existingConfigs = await oauthService.getAllConfigs();
+    const existingProviders = existingConfigs.map((config) => config.provider.toLowerCase());
+
+    // Seed Google OAuth config if not exists
+    if (!existingProviders.includes('google')) {
+      await oauthService.createConfig({
+        provider: 'google',
+        useSharedKey: true,
+      });
+      logger.info('✅ Default Google OAuth config created');
+    }
+
+    // Seed GitHub OAuth config if not exists
+    if (!existingProviders.includes('github')) {
+      await oauthService.createConfig({
+        provider: 'github',
+        useSharedKey: true,
+      });
+      logger.info('✅ Default GitHub OAuth config created');
+    }
+  } catch (error) {
+    logger.warn('Failed to seed OAuth configs', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    // Don't throw error as OAuth configs are optional
+  }
+}
+
+/**
+ * Seeds OAuth configurations from local environment variables
+ */
+async function seedLocalOAuthConfigs(): Promise<void> {
+  const oauthService = OAuthConfigService.getInstance();
+
+  try {
+    // Check if OAuth configs already exist
+    const existingConfigs = await oauthService.getAllConfigs();
+    const existingProviders = existingConfigs.map((config) => config.provider.toLowerCase());
+
+    // Seed Google OAuth config from environment variables if credentials exist
+    const googleClientId = process.env.GOOGLE_CLIENT_ID;
+    const googleClientSecret = process.env.GOOGLE_CLIENT_SECRET;
+
+    if (googleClientId && googleClientSecret && !existingProviders.includes('google')) {
+      await oauthService.createConfig({
+        provider: 'google',
+        clientId: googleClientId,
+        clientSecret: googleClientSecret,
+        scopes: ['openid', 'email', 'profile'],
+        useSharedKey: false,
+      });
+      logger.info('✅ Google OAuth config loaded from environment variables');
+    }
+
+    // Seed GitHub OAuth config from environment variables if credentials exist
+    const githubClientId = process.env.GITHUB_CLIENT_ID;
+    const githubClientSecret = process.env.GITHUB_CLIENT_SECRET;
+
+    if (githubClientId && githubClientSecret && !existingProviders.includes('github')) {
+      await oauthService.createConfig({
+        provider: 'github',
+        clientId: githubClientId,
+        clientSecret: githubClientSecret,
+        scopes: ['user:email'],
+        useSharedKey: false,
+      });
+      logger.info('✅ GitHub OAuth config loaded from environment variables');
+    }
+  } catch (error) {
+    logger.warn('Failed to seed local OAuth configs', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}
+
+// Create api key, admin user, and default AI configs
+export async function seedBackend(): Promise<void> {
+  const secretService = new SecretsService();
+  const dbManager = DatabaseManager.getInstance();
+
+  const adminEmail = process.env.ADMIN_EMAIL || 'admin@example.com';
+  const adminPassword = process.env.ADMIN_PASSWORD || 'change-this-password';
+
+  try {
+    logger.info(`\n🚀 Insforge Backend Starting...`);
+
+    // Validate admin credentials are configured
+    ensureFirstAdmin(adminEmail, adminPassword);
+
+    // Initialize API key (from env or generate)
+    const apiKey = await secretService.initializeApiKey();
+
+    // Get database stats
+    const tables = await dbManager.getUserTables();
+
+    logger.info(`✅ Database connected to PostgreSQL`, {
+      host: process.env.POSTGRES_HOST || 'localhost',
+      port: process.env.POSTGRES_PORT || '5432',
+      database: process.env.POSTGRES_DB || 'insforge',
+    });
+    // Database connection info is already logged above
+
+    if (tables.length > 0) {
+      logger.info(`✅ Found ${tables.length} user tables`);
+    }
+
+    // seed AI configs for cloud environment
+    await seedDefaultAIConfigs();
+
+    // add default OAuth configs in Cloud hosting
+    if (isCloudEnvironment()) {
+      await seedDefaultOAuthConfigs();
+    } else {
+      await seedLocalOAuthConfigs();
+    }
+
+    // Initialize reserved secrets for edge functions
+    // Add INSFORGE_INTERNAL_URL for Deno-to-backend container communication
+    const insforgInternalUrl = 'http://insforge:7130';
+    const existingSecret = await secretService.getSecretByKey('INSFORGE_INTERNAL_URL');
+
+    if (existingSecret === null) {
+      await secretService.createSecret({
+        key: 'INSFORGE_INTERNAL_URL',
+        isReserved: true,
+        value: insforgInternalUrl,
+      });
+      logger.info('✅ System secrets initialized');
+    }
+
+    logger.info(`API key generated: ${apiKey}`);
+    logger.info(`Setup complete:
+      - Save this API key for your apps!
+      - Dashboard: http://localhost:7131
+      - API: http://localhost:7130/api
+    `);
+  } catch (error) {
+    logger.error('Error during setup', {
+      error: error instanceof Error ? error.message : String(error),
+    });
+  }
+}

package/backend/src/utils/sql-parser.ts

@@ -0,0 +1,63 @@
+import splitSqlQuery from '@databases/split-sql-query';
+import sql from '@databases/sql';
+import logger from './logger.js';
+
+/**
+ * Parse a SQL string into individual statements, properly handling:
+ * - String literals with embedded semicolons
+ * - Escaped quotes
+ * - Comments (both -- and block comment style)
+ * - Complex nested statements
+ *
+ * @param sqlText The raw SQL text to parse
+ * @returns Array of SQL statement strings
+ * @throws Error if the SQL cannot be parsed
+ */
+export function parseSQLStatements(sqlText: string): string[] {
+  if (!sqlText || typeof sqlText !== 'string') {
+    throw new Error('SQL text must be a non-empty string');
+  }
+
+  try {
+    // Create an SQLQuery object from the raw SQL string
+    const sqlQuery = sql`${sql.__dangerous__rawValue(sqlText)}`;
+
+    // splitSqlQuery correctly handles:
+    // - String literals with embedded semicolons
+    // - Escaped quotes
+    // - Comments (both -- and /* */ style)
+    // - Complex nested statements
+    const splitResults = splitSqlQuery(sqlQuery);
+
+    // Convert SQLQuery objects back to strings and filter
+    const statements = splitResults
+      .map((query) => {
+        // Extract the raw SQL text from the SQLQuery object
+        // Use a simple formatter that just returns the SQL text
+        const formatted = query.format({
+          escapeIdentifier: (str: string) => `"${str}"`,
+          formatValue: (_value: unknown, index: number) => ({
+            placeholder: `$${index + 1}`,
+            value: _value,
+          }),
+        });
+        return formatted.text.trim();
+      })
+      .filter((s) => {
+        // Remove statements that are only comments or empty
+        const withoutComments = s
+          .replace(/--.*$/gm, '') // Remove line comments
+          .replace(/\/\*[\s\S]*?\*\//g, '') // Remove block comments
+          .trim();
+        return withoutComments.length > 0;
+      });
+
+    logger.debug(`Parsed ${statements.length} SQL statements from input`);
+    return statements;
+  } catch (parseError) {
+    logger.error('Failed to parse SQL:', parseError);
+    throw new Error(
+      `Invalid SQL format: ${parseError instanceof Error ? parseError.message : String(parseError)}`
+    );
+  }
+}

package/backend/src/utils/uuid.ts

@@ -0,0 +1,9 @@
+import crypto from 'crypto';
+
+/**
+ * Generate a UUID v4
+ * @returns A UUID v4 string
+ */
+export function generateUUID(): string {
+  return crypto.randomUUID();
+}

package/backend/src/utils/validations.ts

@@ -0,0 +1,129 @@
+import { AppError } from '@/api/middleware/error.js';
+import { ERROR_CODES } from '@/types/error-constants.js';
+
+export function validateEmail(email: string) {
+  return /^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$/.test(email);
+}
+
+/**
+ * Validates PostgreSQL identifier names (tables, columns, etc.)
+ * Prevents SQL injection and ensures valid PostgreSQL identifiers
+ *
+ * Regex breakdown: ^[^"...]+ means entire string must NOT contain:
+ * - " (double quotes) - could break SQL queries
+ * - \x00-\x1F (ASCII 0-31) - control characters like null, tab, newline
+ * - \x7F (ASCII 127) - DEL character
+ */
+// eslint-disable-next-line no-control-regex
+const IDENTIFIER_REGEX = /^[^"\x00-\x1F\x7F]+$/;
+
+/**
+ * Validates a PostgreSQL identifier (table name, column name, etc.)
+ * @param identifier - The identifier to validate
+ * @param type - Type of identifier for error messages (e.g., 'table', 'column')
+ * @returns true if valid
+ * @throws AppError if invalid
+ */
+export function validateIdentifier(identifier: string, type: string = 'identifier'): boolean {
+  if (!identifier || identifier.trim().length === 0) {
+    throw new AppError(
+      `Invalid ${type} name: cannot be empty`,
+      400,
+      ERROR_CODES.DATABASE_VALIDATION_ERROR,
+      `Please provide a valid ${type} name`
+    );
+  }
+
+  if (!IDENTIFIER_REGEX.test(identifier)) {
+    throw new AppError(
+      `Invalid ${type} name: cannot contain quotes or control characters`,
+      400,
+      ERROR_CODES.DATABASE_VALIDATION_ERROR,
+      `The ${type} name cannot contain double quotes or control characters (tabs, newlines, etc.)`
+    );
+  }
+
+  return true;
+}
+
+/**
+ * Validates a PostgreSQL identifier and returns boolean without throwing
+ * @param identifier - The identifier to validate
+ * @returns true if valid, false if invalid
+ */
+export function isValidIdentifier(identifier: string): boolean {
+  return Boolean(identifier && identifier.trim().length > 0 && IDENTIFIER_REGEX.test(identifier));
+}
+
+/**
+ * Validates table name with additional checks
+ * @param tableName - The table name to validate
+ * @param operation - The operation being performed (optional)
+ * @returns true if valid
+ * @throws AppError if invalid
+ */
+export function validateTableName(tableName: string): boolean {
+  validateIdentifier(tableName, 'table');
+
+  // Prevent access to all other system tables (starting with _)
+  if (tableName.startsWith('_')) {
+    throw new AppError(
+      'Access to system tables is not allowed',
+      403,
+      ERROR_CODES.FORBIDDEN,
+      'System tables (starting with _) cannot be accessed directly'
+    );
+  }
+
+  return true;
+}
+
+/**
+ * Gets a safe error message for identifier validation
+ * @param identifier - The identifier that failed validation
+ * @param type - Type of identifier
+ * @returns Safe error message
+ */
+export function getIdentifierErrorMessage(identifier: string, type: string = 'identifier'): string {
+  if (!identifier || identifier.trim().length === 0) {
+    return `Invalid ${type} name: cannot be empty`;
+  }
+  if (!IDENTIFIER_REGEX.test(identifier)) {
+    return `Invalid ${type} name: cannot contain quotes or control characters`;
+  }
+  return `Invalid ${type} name`;
+}
+
+/**
+ * Escapes special characters for SQL LIKE patterns.
+ * Prevents injection attacks by escaping %, _ and \ characters which have special meaning in SQL LIKE clauses.
+ *
+ * How it works:
+ * - Matches any of: % (wildcard), _ (single char), or \ (escape char)
+ * - Replaces with: \% \_ or \\ respectively
+ * - This allows literal matching of these characters in LIKE patterns
+ *
+ * @param text - Text to escape for use in SQL LIKE pattern
+ * @returns Escaped text safe for SQL LIKE usage
+ * @example escapeSqlLikePattern("test_file%") → "test\_file\%"
+ */
+export function escapeSqlLikePattern(text: string): string {
+  return text.replace(/([%_\\])/g, '\\$1');
+}
+
+/**
+ * Escapes special regex metacharacters for literal matching in regular expressions.
+ * Prevents regex injection by escaping all characters that have special meaning in regex.
+ *
+ * How it works:
+ * - Matches any regex metacharacter: . * + ? ^ $ { } ( ) | [ ] \
+ * - Replaces with escaped version (prefixed with \)
+ * - This allows creating regex patterns that match these characters literally
+ *
+ * @param text - Text to escape for use in regex patterns
+ * @returns Escaped text safe for regex literal matching
+ * @example escapeRegexPattern("test.file(1)") → "test\\.file\\(1\\)"
+ */
+export function escapeRegexPattern(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}