@constructive-io/graphql-server 3.1.1 → 4.0.0

package/errors/404-message.js

@@ -141,7 +141,7 @@ exports.default = (message = "We’re really sorry about that. The service you w
         }
 
         body {
-            background-color: #dde7e9;
+            background-color: #F3F6FA;
             color: #01A1FF;
             font-family: 'Fjalla One', sans-serif;
             position: relative;

package/errors/api-errors.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Typed API Error System
+ *
+ * Provides strongly-typed error hierarchy for the GraphQL server with:
+ * - Consistent error classification
+ * - HTTP status mapping
+ * - Serialization for API responses and logging
+ *
+ * @module errors/api-errors
+ */
+/**
+ * Centralized error code definitions for external use and type safety.
+ * Use these constants instead of string literals for error code comparisons.
+ */
+export declare const ErrorCodes: {
+    readonly DOMAIN_NOT_FOUND: "DOMAIN_NOT_FOUND";
+    readonly API_NOT_FOUND: "API_NOT_FOUND";
+    readonly NO_VALID_SCHEMAS: "NO_VALID_SCHEMAS";
+    readonly SCHEMA_INVALID: "SCHEMA_INVALID";
+    readonly SCHEMA_ACCESS_DENIED: "SCHEMA_ACCESS_DENIED";
+    readonly HANDLER_ERROR: "HANDLER_ERROR";
+    readonly DATABASE_CONNECTION_ERROR: "DATABASE_CONNECTION_ERROR";
+    readonly AMBIGUOUS_TENANT: "AMBIGUOUS_TENANT";
+    readonly ADMIN_AUTH_REQUIRED: "ADMIN_AUTH_REQUIRED";
+};
+/**
+ * Type alias for valid error codes.
+ * Derived from the ErrorCodes constant for type safety.
+ */
+export type ErrorCode = (typeof ErrorCodes)[keyof typeof ErrorCodes];
+/**
+ * Base class for all API errors.
+ *
+ * Provides consistent structure for error handling including:
+ * - Machine-readable error codes
+ * - HTTP status code mapping
+ * - Optional debugging context
+ * - JSON serialization for API responses
+ *
+ * @example
+ * ```typescript
+ * throw new ApiError('CUSTOM_ERROR', 400, 'Something went wrong', { detail: 'info' });
+ * ```
+ */
+export declare class ApiError extends Error {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly context?: Record<string, unknown>;
+    constructor(code: string, statusCode: number, message: string, context?: Record<string, unknown>);
+    /**
+     * Serializes the error for API responses and structured logging.
+     *
+     * @returns Object with error details suitable for JSON serialization
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Thrown when a domain lookup fails to find a matching API.
+ *
+ * @example
+ * ```typescript
+ * throw new DomainNotFoundError('example.com', 'api');
+ * // Results in: "No API configured for domain: api.example.com"
+ * ```
+ */
+export declare class DomainNotFoundError extends ApiError {
+    constructor(domain: string, subdomain: string | null);
+}
+/**
+ * Thrown when a specific API cannot be found by its ID.
+ *
+ * @example
+ * ```typescript
+ * throw new ApiNotFoundError('api-123');
+ * ```
+ */
+export declare class ApiNotFoundError extends ApiError {
+    constructor(apiId: string);
+}
+/**
+ * Thrown when no valid schemas are found for an API.
+ *
+ * @example
+ * ```typescript
+ * throw new NoValidSchemasError('api-123');
+ * ```
+ */
+export declare class NoValidSchemasError extends ApiError {
+    constructor(apiId: string);
+}
+/**
+ * Thrown when schema validation fails.
+ *
+ * @example
+ * ```typescript
+ * throw new SchemaValidationError('Invalid schema structure', { field: 'name' });
+ * ```
+ */
+export declare class SchemaValidationError extends ApiError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Thrown when a request handler cannot be created.
+ *
+ * @example
+ * ```typescript
+ * throw new HandlerCreationError('Failed to create PostGraphile handler', { reason: 'timeout' });
+ * ```
+ */
+export declare class HandlerCreationError extends ApiError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Thrown when the database connection fails.
+ *
+ * @example
+ * ```typescript
+ * throw new DatabaseConnectionError('Connection timeout', { host: 'db.example.com' });
+ * ```
+ */
+export declare class DatabaseConnectionError extends ApiError {
+    constructor(message: string, context?: Record<string, unknown>);
+}
+/**
+ * Thrown when a tenant attempts to access schemas they do not own.
+ * Returns 403 Forbidden to indicate the schemas exist but access is denied.
+ *
+ * Security Note: This error intentionally does not reveal which specific
+ * schemas exist to prevent information disclosure.
+ *
+ * @example
+ * ```typescript
+ * throw new SchemaAccessDeniedError(['schema1', 'schema2'], 'db-123');
+ * ```
+ */
+export declare class SchemaAccessDeniedError extends ApiError {
+    constructor(schemas: string[], databaseId: string);
+}
+/**
+ * Thrown when domain resolution is ambiguous (multiple APIs match).
+ * This is a security concern as it indicates potential misconfiguration
+ * that could lead to unpredictable tenant routing.
+ *
+ * @example
+ * ```typescript
+ * throw new AmbiguousTenantError('example.com', 'api', 2);
+ * ```
+ */
+export declare class AmbiguousTenantError extends ApiError {
+    constructor(domain: string, subdomain: string | null, matchCount: number);
+}
+/**
+ * Thrown when admin authentication is required but not provided or invalid.
+ * Used for private API endpoints that require explicit admin credentials.
+ *
+ * @example
+ * ```typescript
+ * throw new AdminAuthRequiredError('Missing authorization header');
+ * ```
+ */
+export declare class AdminAuthRequiredError extends ApiError {
+    constructor(reason: string);
+}
+/**
+ * Check if an error is an instance of ApiError or any of its subclasses.
+ *
+ * @param error - The value to check
+ * @returns True if error is an ApiError instance
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await resolveApi(req);
+ * } catch (error) {
+ *   if (isApiError(error)) {
+ *     // TypeScript knows error has code, statusCode, context
+ *     console.log(error.code);
+ *     res.status(error.statusCode).json(error.toJSON());
+ *   }
+ * }
+ * ```
+ */
+export declare function isApiError(error: unknown): error is ApiError;
+/**
+ * Check if an error has a specific error code.
+ * Returns false for non-ApiError values.
+ *
+ * @param error - The value to check
+ * @param code - The error code to match against
+ * @returns True if error is an ApiError with the specified code
+ *
+ * @example
+ * ```typescript
+ * if (hasErrorCode(error, ErrorCodes.DOMAIN_NOT_FOUND)) {
+ *   // Handle domain not found specifically
+ *   logDomainMisconfiguration(error.context?.fullDomain);
+ * }
+ * ```
+ */
+export declare function hasErrorCode(error: unknown, code: string): error is ApiError;

package/errors/api-errors.js

@@ -0,0 +1,276 @@
+"use strict";
+/**
+ * Typed API Error System
+ *
+ * Provides strongly-typed error hierarchy for the GraphQL server with:
+ * - Consistent error classification
+ * - HTTP status mapping
+ * - Serialization for API responses and logging
+ *
+ * @module errors/api-errors
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AdminAuthRequiredError = exports.AmbiguousTenantError = exports.SchemaAccessDeniedError = exports.DatabaseConnectionError = exports.HandlerCreationError = exports.SchemaValidationError = exports.NoValidSchemasError = exports.ApiNotFoundError = exports.DomainNotFoundError = exports.ApiError = exports.ErrorCodes = void 0;
+exports.isApiError = isApiError;
+exports.hasErrorCode = hasErrorCode;
+// =============================================================================
+// Error Codes Constant
+// =============================================================================
+/**
+ * Centralized error code definitions for external use and type safety.
+ * Use these constants instead of string literals for error code comparisons.
+ */
+exports.ErrorCodes = {
+    DOMAIN_NOT_FOUND: 'DOMAIN_NOT_FOUND',
+    API_NOT_FOUND: 'API_NOT_FOUND',
+    NO_VALID_SCHEMAS: 'NO_VALID_SCHEMAS',
+    SCHEMA_INVALID: 'SCHEMA_INVALID',
+    SCHEMA_ACCESS_DENIED: 'SCHEMA_ACCESS_DENIED',
+    HANDLER_ERROR: 'HANDLER_ERROR',
+    DATABASE_CONNECTION_ERROR: 'DATABASE_CONNECTION_ERROR',
+    AMBIGUOUS_TENANT: 'AMBIGUOUS_TENANT',
+    ADMIN_AUTH_REQUIRED: 'ADMIN_AUTH_REQUIRED',
+};
+// =============================================================================
+// Base Error Class
+// =============================================================================
+/**
+ * Base class for all API errors.
+ *
+ * Provides consistent structure for error handling including:
+ * - Machine-readable error codes
+ * - HTTP status code mapping
+ * - Optional debugging context
+ * - JSON serialization for API responses
+ *
+ * @example
+ * ```typescript
+ * throw new ApiError('CUSTOM_ERROR', 400, 'Something went wrong', { detail: 'info' });
+ * ```
+ */
+class ApiError extends Error {
+    code;
+    statusCode;
+    context;
+    constructor(code, statusCode, message, context) {
+        super(message);
+        this.code = code;
+        this.statusCode = statusCode;
+        this.context = context;
+        this.name = 'ApiError';
+        // Ensure instanceof checks work correctly with ES5 transpilation
+        Object.setPrototypeOf(this, new.target.prototype);
+        // Capture stack trace for V8 engines (Node.js)
+        // Points to error origin rather than base class constructor
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+    }
+    /**
+     * Serializes the error for API responses and structured logging.
+     *
+     * @returns Object with error details suitable for JSON serialization
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            statusCode: this.statusCode,
+            ...(this.context && { context: this.context }),
+        };
+    }
+}
+exports.ApiError = ApiError;
+// =============================================================================
+// Error Subclasses
+// =============================================================================
+/**
+ * Thrown when a domain lookup fails to find a matching API.
+ *
+ * @example
+ * ```typescript
+ * throw new DomainNotFoundError('example.com', 'api');
+ * // Results in: "No API configured for domain: api.example.com"
+ * ```
+ */
+class DomainNotFoundError extends ApiError {
+    constructor(domain, subdomain) {
+        const fullDomain = subdomain ? `${subdomain}.${domain}` : domain;
+        super(exports.ErrorCodes.DOMAIN_NOT_FOUND, 404, `No API configured for domain: ${fullDomain}`, { domain, subdomain, fullDomain });
+        this.name = 'DomainNotFoundError';
+    }
+}
+exports.DomainNotFoundError = DomainNotFoundError;
+/**
+ * Thrown when a specific API cannot be found by its ID.
+ *
+ * @example
+ * ```typescript
+ * throw new ApiNotFoundError('api-123');
+ * ```
+ */
+class ApiNotFoundError extends ApiError {
+    constructor(apiId) {
+        super(exports.ErrorCodes.API_NOT_FOUND, 404, `API not found: ${apiId}`, { apiId });
+        this.name = 'ApiNotFoundError';
+    }
+}
+exports.ApiNotFoundError = ApiNotFoundError;
+/**
+ * Thrown when no valid schemas are found for an API.
+ *
+ * @example
+ * ```typescript
+ * throw new NoValidSchemasError('api-123');
+ * ```
+ */
+class NoValidSchemasError extends ApiError {
+    constructor(apiId) {
+        super(exports.ErrorCodes.NO_VALID_SCHEMAS, 404, `No valid schemas found for API: ${apiId}`, { apiId });
+        this.name = 'NoValidSchemasError';
+    }
+}
+exports.NoValidSchemasError = NoValidSchemasError;
+/**
+ * Thrown when schema validation fails.
+ *
+ * @example
+ * ```typescript
+ * throw new SchemaValidationError('Invalid schema structure', { field: 'name' });
+ * ```
+ */
+class SchemaValidationError extends ApiError {
+    constructor(message, context) {
+        super(exports.ErrorCodes.SCHEMA_INVALID, 400, message, context);
+        this.name = 'SchemaValidationError';
+    }
+}
+exports.SchemaValidationError = SchemaValidationError;
+/**
+ * Thrown when a request handler cannot be created.
+ *
+ * @example
+ * ```typescript
+ * throw new HandlerCreationError('Failed to create PostGraphile handler', { reason: 'timeout' });
+ * ```
+ */
+class HandlerCreationError extends ApiError {
+    constructor(message, context) {
+        super(exports.ErrorCodes.HANDLER_ERROR, 500, message, context);
+        this.name = 'HandlerCreationError';
+    }
+}
+exports.HandlerCreationError = HandlerCreationError;
+/**
+ * Thrown when the database connection fails.
+ *
+ * @example
+ * ```typescript
+ * throw new DatabaseConnectionError('Connection timeout', { host: 'db.example.com' });
+ * ```
+ */
+class DatabaseConnectionError extends ApiError {
+    constructor(message, context) {
+        super(exports.ErrorCodes.DATABASE_CONNECTION_ERROR, 503, message, context);
+        this.name = 'DatabaseConnectionError';
+    }
+}
+exports.DatabaseConnectionError = DatabaseConnectionError;
+/**
+ * Thrown when a tenant attempts to access schemas they do not own.
+ * Returns 403 Forbidden to indicate the schemas exist but access is denied.
+ *
+ * Security Note: This error intentionally does not reveal which specific
+ * schemas exist to prevent information disclosure.
+ *
+ * @example
+ * ```typescript
+ * throw new SchemaAccessDeniedError(['schema1', 'schema2'], 'db-123');
+ * ```
+ */
+class SchemaAccessDeniedError extends ApiError {
+    constructor(schemas, databaseId) {
+        super(exports.ErrorCodes.SCHEMA_ACCESS_DENIED, 403, `Access denied: requested schemas are not associated with tenant`, { schemas, databaseId });
+        this.name = 'SchemaAccessDeniedError';
+    }
+}
+exports.SchemaAccessDeniedError = SchemaAccessDeniedError;
+/**
+ * Thrown when domain resolution is ambiguous (multiple APIs match).
+ * This is a security concern as it indicates potential misconfiguration
+ * that could lead to unpredictable tenant routing.
+ *
+ * @example
+ * ```typescript
+ * throw new AmbiguousTenantError('example.com', 'api', 2);
+ * ```
+ */
+class AmbiguousTenantError extends ApiError {
+    constructor(domain, subdomain, matchCount) {
+        const fullDomain = subdomain ? `${subdomain}.${domain}` : domain;
+        super(exports.ErrorCodes.AMBIGUOUS_TENANT, 500, `Ambiguous tenant resolution: multiple APIs (${matchCount}) match domain ${fullDomain}`, { domain, subdomain, fullDomain, matchCount });
+        this.name = 'AmbiguousTenantError';
+    }
+}
+exports.AmbiguousTenantError = AmbiguousTenantError;
+/**
+ * Thrown when admin authentication is required but not provided or invalid.
+ * Used for private API endpoints that require explicit admin credentials.
+ *
+ * @example
+ * ```typescript
+ * throw new AdminAuthRequiredError('Missing authorization header');
+ * ```
+ */
+class AdminAuthRequiredError extends ApiError {
+    constructor(reason) {
+        super(exports.ErrorCodes.ADMIN_AUTH_REQUIRED, 401, `Admin authentication required: ${reason}`, { reason });
+        this.name = 'AdminAuthRequiredError';
+    }
+}
+exports.AdminAuthRequiredError = AdminAuthRequiredError;
+// =============================================================================
+// Type Guards
+// =============================================================================
+/**
+ * Check if an error is an instance of ApiError or any of its subclasses.
+ *
+ * @param error - The value to check
+ * @returns True if error is an ApiError instance
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await resolveApi(req);
+ * } catch (error) {
+ *   if (isApiError(error)) {
+ *     // TypeScript knows error has code, statusCode, context
+ *     console.log(error.code);
+ *     res.status(error.statusCode).json(error.toJSON());
+ *   }
+ * }
+ * ```
+ */
+function isApiError(error) {
+    return error instanceof ApiError;
+}
+/**
+ * Check if an error has a specific error code.
+ * Returns false for non-ApiError values.
+ *
+ * @param error - The value to check
+ * @param code - The error code to match against
+ * @returns True if error is an ApiError with the specified code
+ *
+ * @example
+ * ```typescript
+ * if (hasErrorCode(error, ErrorCodes.DOMAIN_NOT_FOUND)) {
+ *   // Handle domain not found specifically
+ *   logDomainMisconfiguration(error.context?.fullDomain);
+ * }
+ * ```
+ */
+function hasErrorCode(error, code) {
+    return isApiError(error) && error.code === code;
+}

package/esm/errors/404-message.js

@@ -139,7 +139,7 @@ export default (message = "We’re really sorry about that. The service you were
         }
 
         body {
-            background-color: #dde7e9;
+            background-color: #F3F6FA;
             color: #01A1FF;
             font-family: 'Fjalla One', sans-serif;
             position: relative;