@hamak/smart-data-dico 1.0.0

package/backend/src/kernel/config.ts

@@ -0,0 +1,43 @@
+/**
+ * Centralized Configuration
+ *
+ * Single source of truth for backend configuration values.
+ * Reads from environment variables with sensible defaults.
+ */
+
+import path from 'path';
+import dotenv from 'dotenv';
+
+dotenv.config();
+
+const isProduction = process.env.NODE_ENV === 'production';
+
+export const config = {
+  /** Server port */
+  port: parseInt(process.env.PORT || '3001', 10),
+
+  /** Base directory for data dictionaries (YAML files) */
+  dataDir: process.env.DATA_DIR
+    || (isProduction
+      ? path.join(process.cwd(), 'data-dictionaries')
+      : path.join(process.cwd(), '..', 'data-dictionaries')),
+
+  /** Deployment profile: local | team | server */
+  profile: (process.env.PROFILE || 'local') as 'local' | 'team' | 'server',
+
+  /** JWT configuration */
+  jwt: {
+    secret: process.env.JWT_SECRET || 'dev-secret-key',
+    expiresIn: process.env.JWT_EXPIRES_IN || '24h',
+  },
+
+  /** Git configuration */
+  git: {
+    /** Whether to auto-commit on entity changes */
+    autoCommit: process.env.GIT_AUTO_COMMIT !== 'false',
+  },
+
+  /** Environment */
+  nodeEnv: process.env.NODE_ENV || 'development',
+  isProduction,
+};

package/backend/src/middleware/auth.ts

@@ -0,0 +1,128 @@
+import { Request, Response, NextFunction } from 'express';
+import { logger } from '../utils/logger.js';
+
+// Interface for user roles
+export enum UserRole {
+  ADMIN = 'admin',
+  EDITOR = 'editor',
+  VIEWER = 'viewer'
+}
+
+// Interface for user information
+export interface User {
+  id: string;
+  username: string;
+  role: UserRole;
+}
+
+/**
+ * Mock user database - in a real application, this would be stored in a database
+ * and passwords would be hashed
+ */
+const users: Record<string, { password: string; user: User }> = {
+  'admin': {
+    password: 'admin123',
+    user: {
+      id: '1',
+      username: 'admin',
+      role: UserRole.ADMIN
+    }
+  },
+  'editor': {
+    password: 'editor123',
+    user: {
+      id: '2',
+      username: 'editor',
+      role: UserRole.EDITOR
+    }
+  },
+  'viewer': {
+    password: 'viewer123',
+    user: {
+      id: '3',
+      username: 'viewer',
+      role: UserRole.VIEWER
+    }
+  }
+};
+
+/**
+ * Basic authentication middleware
+ * Extracts credentials from Authorization header and validates them
+ * @param req Express request
+ * @param res Express response
+ * @param next Next function
+ */
+export const basicAuth = (req: Request, res: Response, next: NextFunction) => {
+  // Get authorization header
+  const authHeader = req.headers.authorization;
+  
+  if (!authHeader || !authHeader.startsWith('Basic ')) {
+    return res.status(401).json({ 
+      message: 'Authentication required',
+      error: 'Missing or invalid Authorization header'
+    });
+  }
+  
+  // Extract and decode credentials
+  try {
+    const base64Credentials = authHeader.split(' ')[1];
+    const credentials = Buffer.from(base64Credentials, 'base64').toString('utf-8');
+    const [username, password] = credentials.split(':');
+    
+    // Validate credentials
+    const userRecord = users[username];
+    
+    if (!userRecord || userRecord.password !== password) {
+      return res.status(401).json({ 
+        message: 'Authentication failed',
+        error: 'Invalid username or password'
+      });
+    }
+    
+    // Add user to request object
+    (req as any).user = userRecord.user;
+    
+    next();
+  } catch (error) {
+    logger.error(`Authentication error: ${error}`);
+    return res.status(401).json({ 
+      message: 'Authentication failed',
+      error: 'Invalid credentials format'
+    });
+  }
+};
+
+/**
+ * Role-based authorization middleware
+ * Checks if the authenticated user has one of the required roles
+ * @param allowedRoles Array of allowed roles
+ * @returns Middleware function
+ */
+export const authenticate = (allowedRoles: UserRole[]) => {
+  return (req: Request, res: Response, next: NextFunction) => {
+    // First apply basic authentication
+    basicAuth(req, res, (err) => {
+      if (err) return next(err);
+      
+      // Check if user has required role
+      const user = (req as any).user as User;
+      
+      if (!user) {
+        return res.status(401).json({ 
+          message: 'Authentication required',
+          error: 'User not authenticated'
+        });
+      }
+      
+      if (!allowedRoles.includes(user.role)) {
+        return res.status(403).json({ 
+          message: 'Access denied',
+          error: 'Insufficient permissions'
+        });
+      }
+      
+      next();
+    });
+  };
+};

package/backend/src/middleware/jwtAuth.ts

@@ -0,0 +1,100 @@
+import { Request, Response, NextFunction } from 'express';
+import jwt from 'jsonwebtoken';
+import { logger } from '../utils/logger.js';
+import { User } from './auth.js';
+
+// JWT secret key - should be in environment variables in production
+const JWT_SECRET = process.env.JWT_SECRET || 'your-secret-key';
+
+/**
+ * JWT authentication middleware
+ * Verifies JWT token from Authorization header
+ * @param req Express request
+ * @param res Express response
+ * @param next Next function
+ */
+export const verifyToken = (req: Request, res: Response, next: NextFunction) => {
+  // Development mode bypass for testing
+  if (process.env.NODE_ENV === 'development' && req.headers.authorization === 'Bearer mock-token-for-testing') {
+    logger.info('Using mock authentication token for development');
+    // Set a mock user for development
+    (req as any).user = {
+      id: 'dev-user',
+      username: 'developer',
+      email: 'dev@example.com',
+      role: 'admin'
+    };
+    return next();
+  }
+
+  // Get authorization header
+  const authHeader = req.headers.authorization;
+  
+  if (!authHeader || !authHeader.startsWith('Bearer ')) {
+    return res.status(401).json({
+      message: 'Authentication required',
+      error: 'Missing or invalid Authorization header'
+    });
+  }
+  
+  // Extract token
+  const token = authHeader.split(' ')[1];
+  
+  try {
+    // Verify token
+    const decoded = jwt.verify(token, JWT_SECRET as jwt.Secret) as User;
+    
+    // Add user to request object
+    (req as any).user = decoded;
+    
+    next();
+  } catch (error: any) {
+    logger.error(`JWT verification error: ${error.message}`);
+    
+    if (error.name === 'TokenExpiredError') {
+      return res.status(401).json({ 
+        message: 'Authentication failed',
+        error: 'Token expired'
+      });
+    }
+    
+    return res.status(401).json({ 
+      message: 'Authentication failed',
+      error: 'Invalid token'
+    });
+  }
+};
+
+/**
+ * Role-based authorization middleware using JWT
+ * Checks if the authenticated user has one of the required roles
+ * @param allowedRoles Array of allowed roles
+ * @returns Middleware function
+ */
+export const authorizeJwt = (allowedRoles: string[]) => {
+  return (req: Request, res: Response, next: NextFunction) => {
+    // First verify token
+    verifyToken(req, res, (err) => {
+      if (err) return next(err);
+      
+      // Check if user has required role
+      const user = (req as any).user as User;
+      
+      if (!user) {
+        return res.status(401).json({ 
+          message: 'Authentication required',
+          error: 'User not authenticated'
+        });
+      }
+      
+      if (!allowedRoles.includes(user.role)) {
+        return res.status(403).json({ 
+          message: 'Access denied',
+          error: 'Insufficient permissions'
+        });
+      }
+      
+      next();
+    });
+  };
+};

package/backend/src/models/Dictionary.ts

@@ -0,0 +1,38 @@
+import { Entity, MetadataDefinition, MetadataEntry, Relationship } from './EntitySchema.js';
+
+/**
+ * Package type annotation
+ */
+export enum PackageType {
+  PROJECT = 'project',
+  MICROSERVICE = 'microservice',
+  MODULE = 'module'
+}
+
+/**
+ * Represents a hierarchical package, which can contain subpackages and/or entities.
+ */
+export interface Package {
+  id: string;
+  name: string;
+  description?: string;
+  type?: PackageType | string;
+  entities: Entity[];
+  subPackages: Package[];
+  relationships: Relationship[];
+  metadata?: MetadataEntry[];
+}
+
+/**
+ * Dictionary model interface.
+ * Supports a hierarchy of packages via the rootPackage property.
+ */
+export interface Dictionary {
+  id: string;
+  name: string;
+  description?: string;
+  metadataDefinitions?: MetadataDefinition[];
+  createdAt?: Date;
+  updatedAt?: Date;
+  rootPackage: Package;
+}

package/backend/src/models/EntitySchema.ts

@@ -0,0 +1,393 @@
+import { Validator } from 'jsonschema';
+import { generateUUID, isValidUUID } from '../utils/uuid.js';
+type Schema = any; // Using any as a workaround for missing type definitions
+
+/**
+ * Supported attribute types in the data dictionary
+ */
+export enum AttributeType {
+  STRING = 'string',
+  NUMBER = 'number',
+  INTEGER = 'integer',
+  BOOLEAN = 'boolean',
+  DATETIME = 'datetime',
+  DATE = 'date',
+  TIME = 'time',
+  DATE_TIME = 'date-time',
+  TIMESTAMP = 'timestamp',
+  DURATION = 'duration',
+  ENUM = 'enum',
+  OBJECT = 'object',
+  ARRAY = 'array'
+}
+
+/**
+ * Cardinality for relationship ends
+ */
+export enum Cardinality {
+  ONE = 'one',
+  MANY = 'many'
+}
+
+/**
+ * Metadata value types for typed metadata definitions
+ */
+export enum MetadataValueType {
+  STRING = 'string',
+  NUMBER = 'number',
+  BOOLEAN = 'boolean',
+  DATE = 'date',
+  FLAG = 'flag',
+  RULE = 'rule',
+}
+
+export enum RuleSeverity {
+  INFO = 'info',
+  WARNING = 'warning',
+  ERROR = 'error',
+}
+
+/**
+ * A metadata definition (schema for metadata entries)
+ */
+export interface MetadataDefinition {
+  name: string;
+  type: MetadataValueType;
+  description?: string;
+  required?: boolean;
+}
+
+/**
+ * A typed metadata entry
+ */
+export interface MetadataEntry {
+  name: string;
+  value: string | number | boolean;
+  severity?: RuleSeverity;
+}
+
+export enum EntityStatus {
+  DRAFT = 'draft',
+  SUBMITTED = 'submitted',
+  APPROVED = 'approved',
+  RETURNED = 'returned',
+}
+
+export interface ReviewComment {
+  id: string;
+  author: string;
+  timestamp: string;
+  message: string;
+  targetField?: string;
+  resolved?: boolean;
+}
+
+export type StereotypeTarget = 'package' | 'entity' | 'attribute';
+
+export interface Stereotype {
+  id: string;
+  name: string;
+  description?: string;
+  appliesTo: StereotypeTarget;
+  metadataDefinitions: MetadataDefinition[];
+}
+
+/**
+ * A node in a perspective — annotates, sets frontier, or excludes a path
+ */
+export interface PerspectiveNode {
+  path: string;
+  traverse?: boolean;
+  exclude?: boolean;
+  metadata?: MetadataEntry[];
+}
+
+/**
+ * A perspective is a business view over a subset of the data model
+ */
+export interface Perspective {
+  uuid: string;
+  name: string;
+  description?: string;
+  rootEntities: string[];
+  nodes?: PerspectiveNode[];
+  maxDepth?: number;
+  metadata?: MetadataEntry[];
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+/**
+ * A resolved node from BFS traversal of a perspective
+ */
+export interface ResolvedNode {
+  entityUuid: string;
+  entityName: string;
+  service: string;
+  path: string;
+  hopDistance: number;
+  isRoot: boolean;
+  isFrontier: boolean;
+  isManualInclusion: boolean;
+}
+
+/**
+ * A perspective with its resolved entity graph
+ */
+export interface ResolvedPerspective extends Perspective {
+  resolvedNodes: ResolvedNode[];
+}
+
+/**
+ * Grouped constraint fields for attributes
+ */
+export interface AttributeConstraints {
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+  format?: string;
+  minimum?: number;
+  maximum?: number;
+  precision?: number;
+  scale?: number;
+  enumValues?: string[];
+}
+
+/**
+ * Interface for entity attribute definition
+ */
+export interface Attribute {
+  uuid: string;
+  name: string;
+  description: string;
+  type: AttributeType;
+  required: boolean;
+  unique?: boolean;
+  primaryKey?: boolean;
+  defaultValue?: any;
+  examples?: any[];
+  constraints?: AttributeConstraints;
+
+  // For object and array types
+  items?: Attribute;
+  properties?: Attribute[];
+
+  // Typed metadata
+  metadata?: MetadataEntry[];
+}
+
+/**
+ * One end of a relationship
+ */
+export interface RelationshipEnd {
+  entity: string; // UUID of the entity
+  cardinality: Cardinality;
+  name?: string; // Navigation property name
+  referenceAttributes?: string[];
+}
+
+/**
+ * A relationship between two entities, stored at package level
+ */
+export type RelationshipType = 'structural' | 'lineage';
+
+export interface Relationship {
+  uuid: string;
+  description?: string;
+  type?: RelationshipType;
+  source: RelationshipEnd;
+  target: RelationshipEnd;
+  metadata?: MetadataEntry[];
+}
+
+export interface LineageNode {
+  entityUuid: string;
+  entityName: string;
+  service: string;
+  direction: 'upstream' | 'downstream';
+  depth: number;
+  relationship: { uuid: string; description: string };
+}
+
+export interface LineageResult {
+  entity: { uuid: string; name: string; service: string };
+  upstream: LineageNode[];
+  downstream: LineageNode[];
+}
+
+/**
+ * Interface for entity definition
+ */
+export interface Entity {
+  uuid: string;
+  name: string;
+  description?: string;
+  stereotype?: string;
+  status?: EntityStatus;
+  attributes: Attribute[];
+  metadata?: MetadataEntry[];
+  createdAt?: string;
+  updatedAt?: string;
+}
+
+// Backward-compatible alias
+export type EntityAttribute = Attribute;
+
+/**
+ * JSON Schema for validating entity definitions
+ */
+export const entitySchema: Schema = {
+  type: 'object',
+  required: ['uuid', 'name', 'attributes'],
+  properties: {
+    uuid: { type: 'string', pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$' },
+    name: { type: 'string' },
+    description: { type: 'string' },
+    attributes: {
+      type: 'array',
+      items: {
+        type: 'object',
+        required: ['uuid', 'name', 'description', 'type', 'required'],
+        properties: {
+          uuid: { type: 'string', pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$' },
+          name: { type: 'string' },
+          description: { type: 'string' },
+          type: {
+            type: 'string',
+            enum: Object.values(AttributeType)
+          },
+          required: { type: 'boolean' },
+          unique: { type: 'boolean' },
+          primaryKey: { type: 'boolean' },
+          defaultValue: { },
+          examples: { type: 'array' },
+          constraints: {
+            type: 'object',
+            properties: {
+              minLength: { type: 'integer', minimum: 0 },
+              maxLength: { type: 'integer', minimum: 0 },
+              pattern: { type: 'string' },
+              format: { type: 'string' },
+              minimum: { type: 'number' },
+              maximum: { type: 'number' },
+              precision: { type: 'integer', minimum: 0 },
+              scale: { type: 'integer', minimum: 0 },
+              enumValues: {
+                type: 'array',
+                items: { type: 'string' }
+              }
+            }
+          },
+          items: { type: 'object' },
+          properties: { type: 'array' },
+          metadata: { type: 'array' }
+        }
+      }
+    },
+    metadata: { type: 'array' },
+    createdAt: { type: 'string', format: 'date-time' },
+    updatedAt: { type: 'string', format: 'date-time' }
+  }
+};
+
+/**
+ * JSON Schema for validating relationship definitions
+ */
+export const relationshipSchema: Schema = {
+  type: 'object',
+  required: ['uuid', 'source', 'target'],
+  properties: {
+    uuid: { type: 'string', pattern: '^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$' },
+    description: { type: 'string' },
+    source: {
+      type: 'object',
+      required: ['entity', 'cardinality'],
+      properties: {
+        entity: { type: 'string' },
+        cardinality: { type: 'string', enum: Object.values(Cardinality) },
+        name: { type: 'string' },
+        referenceAttributes: { type: 'array', items: { type: 'string' } }
+      }
+    },
+    target: {
+      type: 'object',
+      required: ['entity', 'cardinality'],
+      properties: {
+        entity: { type: 'string' },
+        cardinality: { type: 'string', enum: Object.values(Cardinality) },
+        name: { type: 'string' },
+        referenceAttributes: { type: 'array', items: { type: 'string' } }
+      }
+    },
+    metadata: { type: 'array' }
+  }
+};
+
+/**
+ * Validates an entity definition against the schema
+ */
+export function validateEntity(entity: Entity): { valid: boolean; errors: string[] } {
+  const validator = new Validator();
+  const result = validator.validate(entity, entitySchema);
+
+  const errors: string[] = result.errors.map((error: any) => error.stack);
+
+  // Additional UUID validation
+  if (!isValidUUID(entity.uuid)) {
+    errors.push('Entity UUID is invalid');
+  }
+
+  // Validate attribute UUIDs
+  if (entity.attributes) {
+    entity.attributes.forEach((attr, index) => {
+      if (!isValidUUID(attr.uuid)) {
+        errors.push(`Attribute ${index} UUID is invalid`);
+      }
+    });
+  }
+
+  return {
+    valid: result.valid && errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Validates a relationship definition against the schema
+ */
+export function validateRelationship(relationship: Relationship): { valid: boolean; errors: string[] } {
+  const validator = new Validator();
+  const result = validator.validate(relationship, relationshipSchema);
+
+  const errors: string[] = result.errors.map((error: any) => error.stack);
+
+  if (!isValidUUID(relationship.uuid)) {
+    errors.push('Relationship UUID is invalid');
+  }
+
+  return {
+    valid: result.valid && errors.length === 0,
+    errors
+  };
+}
+
+/**
+ * Creates a new entity with UUIDs for all components
+ */
+export function createEntityWithUUIDs(entityData: Omit<Entity, 'uuid' | 'attributes'> & {
+  attributes: Omit<Attribute, 'uuid'>[];
+}): Entity {
+  return {
+    ...entityData,
+    uuid: generateUUID(),
+    attributes: entityData.attributes.map(attr => ({
+      ...attr,
+      uuid: generateUUID(),
+      properties: attr.properties ? attr.properties.map(prop => ({
+        ...prop,
+        uuid: prop.uuid || generateUUID()
+      })) : attr.properties,
+      items: attr.items ? { ...attr.items, uuid: attr.items.uuid || generateUUID() } : attr.items
+    }))
+  };
+}