Add Link Resolver Module with CRUD functionality and DTOs

.env

@@ -9,4 +9,13 @@ DATABASE_URL="postgres://tkawcvceqtdlrt:b63809a94a8d366a92eca1d489dbc43bcc7a58fd
 SHADOW_DATABASE_URL="postgres://kyrhydpwvpavke:7917c48b5ad1e3cfc294df930e053075270752c19bd13c1ea6fd31280722735c@ec2-44-205-112-253.compute-1.amazonaws.com:5432/dfdm5lo7eed2pb"
 
 
-JWT_SECRET='mSSS9Zrd'
+JWT_SECRET='mSSS9Zrd'
+
+# MinIO Configuration
+MINIO_ENDPOINT=localhost
+MINIO_PORT=9000
+MINIO_USE_SSL=false
+MINIO_ACCESS_KEY=minioadmin
+MINIO_SECRET_KEY=minioadmin
+MINIO_BUCKET=link-resolvers
+MINIO_REGION=us-east-1

DATA_INTEGRITY.md

@@ -0,0 +1,98 @@
+# Data Integrity Mechanisms for S3/MinIO Storage
+
+Since S3 and MinIO storage lack the strong consistency guarantees of traditional databases, we have implemented additional data integrity mechanisms to ensure data reliability and prevent corruption or tampering.
+
+## Implementation Details
+
+### 1. SHA-256 Hash Verification
+
+Every data file in our GS1 Identity Resolver system has a corresponding hash file:
+
+- For each `{file}.json`, we maintain a `{file}.hash` file
+- The hash file contains:
+  - A SHA-256 hash of the original data file
+  - A timestamp of when the hash was generated
+
+When retrieving data, the system:
+1. Gets both the data file and its corresponding hash file
+2. Recalculates the SHA-256 hash of the data file
+3. Compares it with the stored hash
+4. Issues warnings if hashes don't match, indicating potential tampering or corruption
+
+### 2. Pre-Update Hash Validation
+
+To prevent concurrent modification conflicts:
+
+1. When retrieving data for modification purposes, the system includes the current hash in the response (as `_hash`)
+2. When updating data, clients must include this original hash
+3. Before processing the update, the system:
+   - Recalculates the current hash of the file
+   - Compares it with the provided hash
+   - Rejects the update if hashes don't match, indicating the file was modified elsewhere
+
+### 3. Immutable History Records
+
+For product data, all changes are recorded in history files:
+
+- History records include their own hash embedded in the record
+- History files are immutable and never modified after creation
+- Each history entry contains complete data at that point in time
+
+### 4. Integrity Verification Tools
+
+The system provides multiple tools to verify data integrity:
+
+#### API Endpoints:
+- `GET /gs1/verify/{entityType}/{entityId}` - Verifies integrity of a specific entity
+- `GET /gs1/verify/metadata` - Verifies system-wide metadata integrity
+
+#### CLI Commands:
+- `yarn gs1:verify -t <entityType> -i <entityId>` - Verifies integrity via command line
+- `./verify-integrity.sh <entityType> <entityId>` - Convenient shell script for verification
+
+## Usage Examples
+
+### Retrieve Data with Hash for Update Operations
+
+```http
+GET /gs1/products/01/12345678901234?includeHash=true
+```
+
+Response includes the `_hash` field:
+```json
+{
+  "id": "01/12345678901234",
+  "name": "Organic Apple Juice",
+  "_hash": "a1b2c3d4e5f6..."
+}
+```
+
+### Update with Hash Validation
+
+```http
+PUT /gs1/products/01/12345678901234
+{
+  "id": "01/12345678901234",
+  "name": "Updated Organic Apple Juice",
+  "_hash": "a1b2c3d4e5f6..."
+}
+```
+
+The system will validate that the hash matches before applying the update.
+
+### Verify Data Integrity
+
+```bash
+# Verify product integrity
+./verify-integrity.sh product 01/12345678901234
+
+# Verify system metadata integrity
+./verify-integrity.sh metadata system
+```
+
+## Benefits
+
+- **Tamper Detection**: Any unauthorized changes to data files can be detected
+- **Corruption Prevention**: Accidental corruption of data during transit or storage can be identified
+- **Optimistic Concurrency**: Prevents conflicting updates without locking
+- **Audit Trail**: History records provide a verifiable audit trail of all changes 

docker-compose.minio.yml

@@ -0,0 +1,17 @@
+version: '3.7'
+
+services:
+  minio:
+    image: minio/minio
+    ports:
+      - "9000:9000"
+      - "9001:9001"
+    environment:
+      MINIO_ROOT_USER: minioadmin
+      MINIO_ROOT_PASSWORD: minioadmin
+    volumes:
+      - minio-data:/data
+    command: server --console-address ":9001" /data
+
+volumes:
+  minio-data: 

initialize-gs1.sh

@@ -0,0 +1,38 @@
+#!/bin/bash
+
+# Start MinIO in the background using Docker Compose
+echo "Starting MinIO..."
+docker-compose -f docker-compose.minio.yml up -d
+
+# Wait a moment for MinIO to fully initialize
+echo "Waiting for MinIO to start..."
+sleep 5
+
+# Run the GS1 initialization command
+echo "Initializing GS1 identity resolver with sample data..."
+yarn ts-node src/cli.ts --gs1 initialize-gs1
+
+# Verify data integrity after initialization
+echo ""
+echo "Verifying data integrity of the system metadata..."
+yarn ts-node src/cli.ts --gs1 verify-integrity -t metadata -i system
+
+echo ""
+echo "Verifying data integrity of a sample product..."
+yarn ts-node src/cli.ts --gs1 verify-integrity -t product -i "01/12345678901234"
+
+echo ""
+echo "GS1 Identity Resolver has been initialized!"
+echo "You can access MinIO console at: http://localhost:9001"
+echo "Login with: minioadmin / minioadmin"
+echo "Check the gs1-identity-resolver bucket for your data"
+echo ""
+echo "To test the API, try these endpoints:"
+echo "- http://localhost:3000/gs1/products/01/12345678901234"
+echo "- http://localhost:3000/gs1/products/01/12345678901235/10/ABC123"
+echo "- http://localhost:3000/gs1/01/12345678901234 (Digital Link)"
+echo ""
+echo "To verify data integrity via API:"
+echo "- http://localhost:3000/gs1/verify/product/01/12345678901234"
+echo "- http://localhost:3000/gs1/verify/metadata/system"
+echo "" 

package.json

@@ -18,21 +18,31 @@
     "test:watch": "jest --watch",
     "test:cov": "jest --coverage",
     "test:debug": "node --inspect-brk -r tsconfig-paths/register -r ts-node/register node_modules/.bin/jest --runInBand",
-    "test:e2e": "jest --config ./test/jest-e2e.json"
+    "test:e2e": "jest --config ./test/jest-e2e.json",
+    "cli:dev": "ts-node src/cli.ts",
+    "cli:build": "nest build && node dist/cli.js",
+    "save-sample": "ts-node src/cli.ts save-sample",
+    "gs1:init": "ts-node src/cli.ts --gs1 initialize-gs1",
+    "gs1:start": "./initialize-gs1.sh",
+    "gs1:verify": "ts-node src/cli.ts --gs1 verify-integrity",
+    "gs1:verify:script": "./verify-integrity.sh"
   },
   "dependencies": {
+    "@aws-sdk/client-s3": "^3.777.0",
+    "@aws-sdk/s3-request-presigner": "^3.777.0",
     "@nestjs/common": "^9.0.0",
-    "@nestjs/config": "^2.2.0",
+    "@nestjs/config": "^4.0.2",
     "@nestjs/core": "^9.0.0",
     "@nestjs/jwt": "^9.0.0",
     "@nestjs/passport": "^9.0.0",
     "@nestjs/platform-express": "^9.0.0",
     "@prisma/client": "^4.1.1",
     "bcrypt": "^5.0.1",
     "class-transformer": "^0.5.1",
-    "class-validator": "^0.13.2",
+    "class-validator": "^0.14.1",
     "cookie-parser": "^1.4.6",
     "csurf": "^1.11.0",
+    "nest-commander": "^3.17.0",
     "passport": "^0.6.0",
     "passport-jwt": "^4.0.0",
     "reflect-metadata": "^0.1.13",

save-to-minio.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+
+# Start MinIO in the background
+echo "Starting MinIO..."
+docker-compose -f docker-compose.minio.yml up -d
+
+# Wait for MinIO to start
+echo "Waiting for MinIO to start..."
+sleep 5
+
+# Save the sample data
+echo "Saving sample data to MinIO..."
+yarn save-sample
+
+echo "Done!"
+echo "The MinIO console is available at http://localhost:9001 (login with minioadmin/minioadmin)"
+echo "The link resolver data is saved to the 'link-resolvers' bucket" 

src/app.module.ts

@@ -6,6 +6,9 @@ import { UserModule } from './user/user.module';
 import { TodoModule } from './todo/todo.module';
 import { PrismaModule } from './prisma/prisma.module';
 import { ConfigModule } from '@nestjs/config';
+import { LinkResolverModule } from './link-resolver/link-resolver.module';
+import { StorageModule } from './storage/storage.module';
+import { GS1Module } from './gs1/gs1.module';
 
 @Module({
   imports: [
@@ -14,6 +17,9 @@ import { ConfigModule } from '@nestjs/config';
     UserModule,
     TodoModule,
     PrismaModule,
+    LinkResolverModule,
+    StorageModule,
+    GS1Module,
   ],
   controllers: [AppController],
   providers: [AppService],

src/cli.ts

@@ -0,0 +1,26 @@
+import { CommandFactory } from 'nest-commander';
+import { LinkResolverCommandsModule } from './link-resolver/commands/commands.module';
+import { GS1CommandsModule } from './gs1/commands/gs1-commands.module';
+
+async function bootstrap() {
+  // To run LinkResolver commands
+  if (process.argv.includes('--link-resolver')) {
+    await CommandFactory.run(LinkResolverCommandsModule, {
+      logger: ['error', 'warn'],
+    });
+  } 
+  // To run GS1 commands
+  else if (process.argv.includes('--gs1')) {
+    await CommandFactory.run(GS1CommandsModule, {
+      logger: ['error', 'warn'],
+    });
+  }
+  // Default to LinkResolver commands for backward compatibility
+  else {
+    await CommandFactory.run(LinkResolverCommandsModule, {
+      logger: ['error', 'warn'],
+    });
+  }
+}
+
+bootstrap(); 

src/common/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Common Barrel File
+ *
+ * This file exports all common elements from the common directory,
+ * making them easier to import elsewhere in the application.
+ */
+
+export * from './interfaces';

src/common/interfaces/index.ts

@@ -0,0 +1,8 @@
+/**
+ * Interfaces Barrel File
+ *
+ * This file exports all interfaces from the interfaces directory,
+ * making them easier to import elsewhere in the application.
+ */
+
+export * from './repository.interface';

src/common/interfaces/repository.interface.ts

@@ -0,0 +1,55 @@
+/**
+ * Repository Provider Interface
+ *
+ * This file defines a TypeScript interface for a repository provider,
+ * which is a common pattern in software architecture for abstracting data access operations.
+ */
+
+/**
+ * Defines the structure for data being saved
+ * Requires an id property as a string
+ * Allows any additional properties
+ */
+export type SaveParams = {
+  id: string;
+  [k: string]: any;
+};
+
+/**
+ * Repository Provider Interface
+ *
+ * Defines four standard CRUD operations:
+ * - save: Stores data with the given parameters
+ * - one: Retrieves a single item by ID
+ * - all: Retrieves all items of a specific category
+ * - delete: Removes an item by ID
+ */
+export interface IRepositoryProvider {
+  /**
+   * Stores data with the given parameters
+   * @param data The data to be saved
+   * @returns A promise resolving to void
+   */
+  save(data: SaveParams): Promise<void>;
+
+  /**
+   * Retrieves a single item by ID
+   * @param id The unique identifier of the item
+   * @returns A promise resolving to the requested item or null if not found
+   */
+  one<T>(id: string): Promise<T | null>;
+
+  /**
+   * Retrieves all items of a specific category
+   * @param filter Optional filtering criteria
+   * @returns A promise resolving to an array of items
+   */
+  all<T>(filter?: object): Promise<T[]>;
+
+  /**
+   * Removes an item by ID
+   * @param id The unique identifier of the item to delete
+   * @returns A promise resolving to void
+   */
+  delete(id: string): Promise<void>;
+}

src/common/utils/hash.util.ts

@@ -0,0 +1,29 @@
+import { createHash } from 'crypto';
+
+/**
+ * Utility class for handling SHA-256 hash operations
+ */
+export class HashUtil {
+  /**
+   * Generate a SHA-256 hash of the provided data
+   * 
+   * @param data Any data that can be converted to string
+   * @returns SHA-256 hash as hexadecimal string
+   */
+  static generateSHA256(data: any): string {
+    const content = typeof data === 'string' ? data : JSON.stringify(data);
+    return createHash('sha256').update(content).digest('hex');
+  }
+
+  /**
+   * Verify if the provided hash matches the hash of the data
+   * 
+   * @param data Data to verify
+   * @param hash Expected hash
+   * @returns Boolean indicating if hash matches
+   */
+  static verifySHA256(data: any, hash: string): boolean {
+    const calculatedHash = this.generateSHA256(data);
+    return calculatedHash === hash;
+  }
+}