@friggframework/schemas 2.0.0-next.78 → 2.0.0-next.80

package/middleware/schema-validation.js

@@ -0,0 +1,388 @@
+/**
+ * Schema Validation Middleware for Express
+ *
+ * Provides request and response validation against JSON schemas using AJV.
+ * Like TypeScript for APIs - enforces contracts at runtime.
+ */
+
+const Ajv = require('ajv');
+const addFormats = require('ajv-formats');
+const fs = require('fs');
+const path = require('path');
+
+// Initialize AJV with formats
+const ajv = new Ajv({
+    allErrors: true,
+    verbose: true,
+    strict: false
+    // Note: coerceTypes disabled to avoid conflicts with oneOf schemas
+});
+addFormats(ajv);
+
+// Load all schemas
+const schemaDir = path.join(__dirname, '..', 'schemas');
+const schemaFiles = [
+    'api-entities.schema.json',
+    'api-credentials.schema.json',
+    'api-proxy.schema.json',
+    'api-authorization.schema.json'
+];
+
+schemaFiles.forEach(file => {
+    const schemaPath = path.join(schemaDir, file);
+    if (fs.existsSync(schemaPath)) {
+        const schemaContent = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+        const schemaName = file.replace('.schema.json', '');
+        ajv.addSchema(schemaContent, schemaName);
+    }
+});
+
+/**
+ * Validation error class for schema validation failures
+ */
+class SchemaValidationError extends Error {
+    constructor(message, errors, location) {
+        super(message);
+        this.name = 'SchemaValidationError';
+        this.errors = errors;
+        this.location = location; // 'body', 'query', 'params', 'response'
+        this.statusCode = location === 'response' ? 500 : 400;
+    }
+
+    toJSON() {
+        return {
+            error: 'ValidationError',
+            message: this.message,
+            location: this.location,
+            details: this.errors.map(err => ({
+                path: err.instancePath || 'root',
+                message: err.message,
+                params: err.params
+            }))
+        };
+    }
+}
+
+/**
+ * Format AJV errors into human-readable messages
+ * @param {Array} errors - AJV validation errors
+ * @returns {string} - Formatted error message
+ */
+function formatValidationErrors(errors) {
+    if (!errors || errors.length === 0) {
+        return 'Unknown validation error';
+    }
+
+    return errors.map(error => {
+        const path = error.instancePath || 'root';
+        const message = error.message;
+        const allowedValues = error.params?.allowedValues
+            ? ` (allowed: ${error.params.allowedValues.join(', ')})`
+            : '';
+        return `${path}: ${message}${allowedValues}`;
+    }).join('; ');
+}
+
+/**
+ * Get a compiled validator for a schema reference
+ * @param {string} schemaRef - Schema reference (e.g., 'api-entities#/definitions/entity')
+ * @returns {Function} - Compiled AJV validator
+ */
+function getValidator(schemaRef) {
+    const validator = ajv.getSchema(schemaRef);
+    if (!validator) {
+        throw new Error(`Schema not found: ${schemaRef}`);
+    }
+    return validator;
+}
+
+/**
+ * Validate request body against a schema
+ * @param {string} schemaRef - Schema reference
+ * @param {Object} options - Validation options
+ * @param {boolean} options.strict - If true, throws on validation failure (default: true)
+ * @param {boolean} options.coerceTypes - If true, coerces types (default: false for body)
+ * @returns {Function} - Express middleware
+ */
+function validateBody(schemaRef, options = {}) {
+    const { strict = true } = options;
+
+    return (req, res, next) => {
+        try {
+            const validator = getValidator(schemaRef);
+            const valid = validator(req.body);
+
+            if (!valid) {
+                const error = new SchemaValidationError(
+                    `Request body validation failed: ${formatValidationErrors(validator.errors)}`,
+                    validator.errors,
+                    'body'
+                );
+
+                if (strict) {
+                    return res.status(400).json(error.toJSON());
+                }
+
+                // Non-strict: attach errors but continue
+                req.validationErrors = req.validationErrors || {};
+                req.validationErrors.body = validator.errors;
+            }
+
+            next();
+        } catch (err) {
+            next(err);
+        }
+    };
+}
+
+/**
+ * Validate query parameters against a schema
+ * @param {string} schemaRef - Schema reference
+ * @param {Object} options - Validation options
+ * @returns {Function} - Express middleware
+ */
+function validateQuery(schemaRef, options = {}) {
+    const { strict = true } = options;
+
+    return (req, res, next) => {
+        try {
+            const validator = getValidator(schemaRef);
+            const valid = validator(req.query);
+
+            if (!valid) {
+                const error = new SchemaValidationError(
+                    `Query parameter validation failed: ${formatValidationErrors(validator.errors)}`,
+                    validator.errors,
+                    'query'
+                );
+
+                if (strict) {
+                    return res.status(400).json(error.toJSON());
+                }
+
+                req.validationErrors = req.validationErrors || {};
+                req.validationErrors.query = validator.errors;
+            }
+
+            next();
+        } catch (err) {
+            next(err);
+        }
+    };
+}
+
+/**
+ * Validate route parameters against a schema
+ * @param {string} schemaRef - Schema reference
+ * @param {Object} options - Validation options
+ * @returns {Function} - Express middleware
+ */
+function validateParams(schemaRef, options = {}) {
+    const { strict = true } = options;
+
+    return (req, res, next) => {
+        try {
+            const validator = getValidator(schemaRef);
+            const valid = validator(req.params);
+
+            if (!valid) {
+                const error = new SchemaValidationError(
+                    `Route parameter validation failed: ${formatValidationErrors(validator.errors)}`,
+                    validator.errors,
+                    'params'
+                );
+
+                if (strict) {
+                    return res.status(400).json(error.toJSON());
+                }
+
+                req.validationErrors = req.validationErrors || {};
+                req.validationErrors.params = validator.errors;
+            }
+
+            next();
+        } catch (err) {
+            next(err);
+        }
+    };
+}
+
+/**
+ * Validate response body against a schema (for development/testing)
+ * Wraps res.json() to validate response data
+ * @param {string} schemaRef - Schema reference
+ * @param {Object} options - Validation options
+ * @returns {Function} - Express middleware
+ */
+function validateResponse(schemaRef, options = {}) {
+    const { strict = false, logErrors = true } = options;
+
+    return (req, res, next) => {
+        const originalJson = res.json.bind(res);
+
+        res.json = function(data) {
+            try {
+                const validator = getValidator(schemaRef);
+                const valid = validator(data);
+
+                if (!valid) {
+                    const errorMessage = formatValidationErrors(validator.errors);
+
+                    if (logErrors) {
+                        console.error(`Response validation failed for ${req.method} ${req.path}:`, errorMessage);
+                    }
+
+                    if (strict) {
+                        const error = new SchemaValidationError(
+                            `Response validation failed: ${errorMessage}`,
+                            validator.errors,
+                            'response'
+                        );
+                        return originalJson.call(res.status(500), error.toJSON());
+                    }
+
+                    // Non-strict: log but continue
+                    // Optionally add validation metadata to response
+                    if (options.includeMetadata) {
+                        data._validation = {
+                            valid: false,
+                            errors: validator.errors
+                        };
+                    }
+                }
+            } catch (err) {
+                if (logErrors) {
+                    console.error('Response validation error:', err.message);
+                }
+            }
+
+            return originalJson.call(res, data);
+        };
+
+        next();
+    };
+}
+
+/**
+ * Combined validation middleware - validates request and response
+ * @param {Object} config - Validation configuration
+ * @param {string} config.body - Schema ref for body validation
+ * @param {string} config.query - Schema ref for query validation
+ * @param {string} config.params - Schema ref for params validation
+ * @param {string} config.response - Schema ref for response validation
+ * @param {Object} config.options - Validation options
+ * @returns {Array<Function>} - Array of Express middleware
+ */
+function validate(config = {}) {
+    const middlewares = [];
+    const { options = {} } = config;
+
+    if (config.body) {
+        middlewares.push(validateBody(config.body, options));
+    }
+
+    if (config.query) {
+        middlewares.push(validateQuery(config.query, options));
+    }
+
+    if (config.params) {
+        middlewares.push(validateParams(config.params, options));
+    }
+
+    if (config.response) {
+        middlewares.push(validateResponse(config.response, options));
+    }
+
+    return middlewares;
+}
+
+/**
+ * Schema reference helpers for common API schemas
+ */
+const SchemaRefs = {
+    // Entities
+    entity: 'api-entities#/definitions/entity',
+    listEntitiesResponse: 'api-entities#/definitions/listEntitiesResponse',
+    createEntityRequest: 'api-entities#/definitions/createEntityRequest',
+    createEntityResponse: 'api-entities#/definitions/createEntityResponse',
+    entityType: 'api-entities#/definitions/entityType',
+    listEntityTypesResponse: 'api-entities#/definitions/listEntityTypesResponse',
+    getEntityTypeResponse: 'api-entities#/definitions/getEntityTypeResponse',
+    reauthorizeEntityRequest: 'api-entities#/definitions/reauthorizeEntityRequest',
+    reauthorizeEntityResponse: 'api-entities#/definitions/reauthorizeEntityResponse',
+
+    // Credentials
+    credential: 'api-credentials#/definitions/credential',
+    listCredentialsResponse: 'api-credentials#/definitions/listCredentialsResponse',
+    getCredentialResponse: 'api-credentials#/definitions/getCredentialResponse',
+    deleteCredentialResponse: 'api-credentials#/definitions/deleteCredentialResponse',
+    reauthorizeCredentialRequest: 'api-credentials#/definitions/reauthorizeCredentialRequest',
+    reauthorizeCredentialResponse: 'api-credentials#/definitions/reauthorizeCredentialResponse',
+
+    // Proxy
+    proxyRequest: 'api-proxy#/definitions/proxyRequest',
+    proxyResponse: 'api-proxy#/definitions/proxyResponse',
+    proxyErrorResponse: 'api-proxy#/definitions/proxyErrorResponse',
+    proxyResponseUnion: 'api-proxy#/definitions/proxyResponseUnion',
+
+    // Authorization
+    authorizationRequirements: 'api-authorization#/definitions/authorizationRequirements',
+    authorizationRequest: 'api-authorization#/definitions/authorizationRequest',
+    authorizationResponse: 'api-authorization#/definitions/authorizationResponse',
+    authorizationSession: 'api-authorization#/definitions/authorizationSession',
+    getEntityTypeRequirementsResponse: 'api-authorization#/definitions/getEntityTypeRequirementsResponse'
+};
+
+/**
+ * Precompiled validators for performance
+ */
+const Validators = {};
+
+// Lazy-load validators on first use
+function getCompiledValidator(name) {
+    if (!Validators[name]) {
+        const ref = SchemaRefs[name];
+        if (!ref) {
+            throw new Error(`Unknown schema name: ${name}`);
+        }
+        Validators[name] = getValidator(ref);
+    }
+    return Validators[name];
+}
+
+/**
+ * Direct validation functions (not middleware)
+ * Useful for testing and manual validation
+ */
+function validateData(schemaName, data) {
+    const validator = getCompiledValidator(schemaName);
+    const valid = validator(data);
+    return {
+        valid,
+        errors: valid ? null : validator.errors,
+        formatted: valid ? null : formatValidationErrors(validator.errors)
+    };
+}
+
+module.exports = {
+    // Middleware
+    validateBody,
+    validateQuery,
+    validateParams,
+    validateResponse,
+    validate,
+
+    // Direct validation
+    validateData,
+    getValidator,
+    formatValidationErrors,
+
+    // Schema references
+    SchemaRefs,
+
+    // Error class
+    SchemaValidationError,
+
+    // AJV instance (for advanced use)
+    ajv
+};

package/mocks/README.md

@@ -0,0 +1,280 @@
+# Authorization Mocks
+
+Schema-compliant mock data generators for testing authentication and authorization flows across the Frigg Framework.
+
+## Purpose
+
+These mocks ensure consistency across all Frigg packages:
+- `@friggframework/core` - Backend authorization logic
+- `@friggframework/ui` - Frontend integration components
+- `@friggframework/devtools/management-ui` - Developer tooling
+
+All mock data is **validated against canonical JSON schemas** to guarantee accuracy.
+
+## Installation
+
+```bash
+npm install @friggframework/schemas
+```
+
+## Usage
+
+### Basic Examples
+
+```javascript
+const {
+    createOAuth2Requirements,
+    createFormRequirements,
+    createNagarisOTPFlowMock,
+    createAuthorizationSuccess,
+} = require('@friggframework/schemas/mocks/authorization-mocks');
+
+// OAuth2 flow
+const hubspotAuth = createOAuth2Requirements('hubspot');
+// {
+//   type: 'oauth2',
+//   step: 1,
+//   totalSteps: 1,
+//   isMultiStep: false,
+//   data: {
+//     url: 'https://auth.hubspot.com/oauth/authorize?...',
+//     scopes: ['read', 'write']
+//   }
+// }
+
+// Form-based auth
+const apiKeyAuth = createFormRequirements('custom-api', {
+    fields: ['api_key']
+});
+// {
+//   type: 'form',
+//   data: {
+//     jsonSchema: { ... },
+//     uiSchema: { ... }
+//   }
+// }
+
+// Multi-step OTP flow (like Nagaris)
+const nagarisFlow = createNagarisOTPFlowMock('user-123');
+const step1Reqs = nagarisFlow.getStep1Requirements(); // Email form
+const step1Response = nagarisFlow.submitStep1({ email: 'test@example.com' }); // OTP sent
+const step2Response = nagarisFlow.submitStep2({ otp: '123456' }); // Success
+```
+
+### In Tests
+
+#### Core Package Tests
+
+```javascript
+// packages/core/__tests__/authorization-flow.test.js
+const { createNagarisOTPFlowMock } = require('@friggframework/schemas/mocks/authorization-mocks');
+const { validateAuthorizationSession } = require('@friggframework/schemas');
+
+test('processes multi-step auth', async () => {
+    const mockFlow = createNagarisOTPFlowMock('user-123');
+    const session = mockFlow.session;
+
+    // Validate before storing
+    const validation = validateAuthorizationSession(session);
+    expect(validation.valid).toBe(true);
+
+    // Use in repository test
+    await authSessionRepository.create(session);
+});
+```
+
+#### UI Package Tests
+
+```javascript
+// packages/ui/__tests__/AuthorizationWizard.test.jsx
+const { createFormRequirements } = require('@friggframework/schemas/mocks/authorization-mocks');
+
+test('renders multi-step OTP form', async () => {
+    const mockApi = {
+        getAuthorizationRequirements: jest.fn().mockResolvedValue(
+            createFormRequirements('nagaris', {
+                fields: ['email'],
+                isMultiStep: true,
+                step: 1,
+                totalSteps: 2
+            })
+        )
+    };
+
+    render(<AuthorizationWizard api={mockApi} moduleType="nagaris" />);
+    // Test form rendering...
+});
+```
+
+#### Management UI Tests
+
+```javascript
+// packages/devtools/management-ui/__tests__/TestingZone.test.jsx
+const { createOAuth2Requirements } = require('@friggframework/schemas/mocks/authorization-mocks');
+
+test('displays OAuth authorization URL', () => {
+    const mockData = createOAuth2Requirements('hubspot');
+
+    render(<AuthFlowDisplay requirements={mockData} />);
+    expect(screen.getByText(/hubspot.com\/oauth/)).toBeInTheDocument();
+});
+```
+
+## API Reference
+
+### OAuth2 Flows
+
+#### `createOAuth2Requirements(moduleType, options)`
+
+Create OAuth2 authorization requirements.
+
+**Parameters:**
+- `moduleType` (string): Module name (e.g., 'hubspot', 'salesforce')
+- `options.scopes` (array): OAuth scopes (default: ['read', 'write'])
+- `options.isMultiStep` (boolean): Multi-step flow (default: false)
+- `options.step` (number): Current step (default: 1)
+- `options.totalSteps` (number): Total steps (default: 1)
+- `options.sessionId` (string): Session ID for multi-step
+
+**Returns:** Authorization requirements object (validated against schema)
+
+#### `createOAuth2FlowMock(moduleType, userId)`
+
+Create complete OAuth2 flow with methods for each step.
+
+**Returns:** Object with `getRequirements()` and `handleCallback()` methods
+
+### Form-Based Flows
+
+#### `createFormRequirements(moduleType, options)`
+
+Create form-based authorization requirements with JSON Schema.
+
+**Parameters:**
+- `moduleType` (string): Module name
+- `options.fields` (array): Field names (email, password, api_key, otp, etc.)
+- `options.isMultiStep` (boolean): Multi-step flow
+- `options.step` (number): Current step
+- `options.totalSteps` (number): Total steps
+- `options.sessionId` (string): Session ID
+
+**Returns:** Form requirements with jsonSchema and uiSchema
+
+**Supported Fields:**
+- `email` - Email input with validation
+- `password` - Password input (min 6 chars)
+- `api_key` - API key text input
+- `otp` - 6-digit OTP input with pattern validation
+- Custom fields - Generic text inputs
+
+### Multi-Step OTP Flows
+
+#### `createOTPMultiStepFlow(moduleType)`
+
+Create multi-step flow structure (email → OTP).
+
+**Returns:** Object with `step1` and `step2(sessionId)` properties
+
+#### `createNagarisOTPFlowMock(userId)`
+
+Create complete Nagaris-style OTP flow with all steps.
+
+**Returns:** Object with methods:
+- `getStep1Requirements()` - Get email form
+- `submitStep1(emailData)` - Submit email, get OTP prompt
+- `submitStep2(otpData)` - Submit OTP, get success
+- `session` - Authorization session object
+- `sessionId` - Session identifier
+- `email` - Test email address
+
+### Response Builders
+
+#### `createAuthorizationSuccess(moduleType, options)`
+
+Create successful authorization response.
+
+**Parameters:**
+- `moduleType` (string): Module name
+- `options.entityId` (string): Entity ID (auto-generated if not provided)
+- `options.credentialId` (string): Credential ID (auto-generated)
+- `options.display` (string): Display name
+
+**Returns:** Success response object
+
+#### `createAuthorizationNextStep(nextStep, requirements, options)`
+
+Create next step response for multi-step flows.
+
+**Parameters:**
+- `nextStep` (number): Next step number
+- `requirements` (object): Requirements for next step
+- `options.sessionId` (string): Session ID (auto-generated)
+- `options.message` (string): User message
+
+**Returns:** Next step response object
+
+### Session Management
+
+#### `createAuthorizationSession(userId, entityType, options)`
+
+Create authorization session database object.
+
+**Parameters:**
+- `userId` (string): User ID
+- `entityType` (string): Module type
+- `options.currentStep` (number): Current step (default: 1)
+- `options.maxSteps` (number): Total steps (default: 2)
+- `options.stepData` (object): Data from previous steps
+- `options.expiresInMinutes` (number): Expiration time (default: 15)
+- `options.completed` (boolean): Completion status
+
+**Returns:** Session object ready for database storage
+
+#### `generateSessionId()`
+
+Generate a UUID v4 session ID.
+
+**Returns:** UUID string
+
+## Validation
+
+All mock data is validated against schemas in `packages/schemas/schemas/api-authorization.schema.json`.
+
+```javascript
+const { validateAuthorizationRequirements } = require('@friggframework/schemas');
+
+const mockData = createFormRequirements('nagaris', { fields: ['email'] });
+const result = validateAuthorizationRequirements(mockData);
+
+if (result.valid) {
+    console.log('✅ Mock data is schema-compliant');
+} else {
+    console.error('❌ Validation errors:', result.errors);
+}
+```
+
+## Testing
+
+Run the mock validation tests:
+
+```bash
+cd packages/schemas
+npm test mocks/__tests__/authorization-mocks.test.js
+```
+
+All tests validate that mocks are schema-compliant and work across packages.
+
+## Contributing
+
+When adding new authorization types:
+
+1. Add schema definition to `api-authorization.schema.json`
+2. Add mock generator to `authorization-mocks.js`
+3. Add validation tests to `__tests__/authorization-mocks.test.js`
+4. Update this README with usage examples
+
+## Related
+
+- [API Authorization Schema](../schemas/api-authorization.schema.json)
+- [Core Authorization Use Cases](../../core/modules/use-cases/)
+- [UI Authorization Components](../../ui/lib/integration/presentation/components/)