fix(kyc): remove requireSeller from document submission endpoints (#626)

.agents/tasks/task-notification-service-564/features/FEAT-001.json

@@ -0,0 +1,28 @@
+{
+  "id": "FEAT-001",
+  "type": "feat",
+  "description": "Add missing NotificationType enum values and wire KYC status-change notifications. Adds KYC_STATUS_CHANGE and SECONDARY_MARKET_SOLD to the enum in src/types/enums.ts, then adds an optional notificationService dependency to KycService and fires createNotification after processWebhook commits a status change. Independent of FEAT-002.",
+  "status": "completed",
+  "steps": [
+    "1. In src/types/enums.ts, append two entries to the NotificationType enum: KYC_STATUS_CHANGE = 'kyc_status_change' and SECONDARY_MARKET_SOLD = 'secondary_market_sold'.",
+    "2. In src/services/kyc.service.ts, add two imports at the top: `import { NotificationService } from './notification.service'` (type-only is fine) and add NotificationType to the existing enums import from '../types/enums'.",
+    "3. In KycService constructor signature, add a fourth optional parameter: `private readonly notificationService?: NotificationService`. Constructor is: `constructor(private readonly dataSource: DataSource, private readonly webhookSecret: string, private readonly appLogger: AppLogger = logger, private readonly notificationService?: NotificationService)`.",
+    "4. In KycService.processWebhook(), after the `await this.dataSource.transaction(...)` call completes (but before the method returns), add a try/catch block that calls this.notificationService?.createNotification(payload.userId, notifType, title, message, { status: payload.status, reason: payload.reason ?? null }). Map KYCStatus.APPROVED → NotificationType.KYC_APPROVED with title 'KYC Approved' and message 'Your identity verification has been approved.'. Map KYCStatus.REJECTED → NotificationType.KYC_REJECTED with title 'KYC Status Updated' and message `Your KYC status has changed to ${payload.status}.`. Catch any error and call this.appLogger.warn('kyc.notification.failed', { user_id: payload.userId, error: ... }) — never rethrow.",
+    "5. In src/index.ts, update the KycService constructor call from `new KycService(dataSource, config.kyc.webhookSecret ?? '', logger)` to `new KycService(dataSource, config.kyc.webhookSecret ?? '', logger, notificationService)`. The notificationService variable is already defined earlier in bootstrap()."
+  ],
+  "acceptance_criteria": [
+    "src/types/enums.ts compiles and exports KYC_STATUS_CHANGE and SECONDARY_MARKET_SOLD values.",
+    "KycService constructor accepts an optional fourth parameter of type NotificationService.",
+    "After processWebhook commits, if notificationService is provided, createNotification is called with the user's id, the correct type (KYC_APPROVED or KYC_REJECTED), and appropriate title/message.",
+    "If createNotification throws, processWebhook still returns successfully and logs a warn.",
+    "All existing KYC tests pass without modification: `npx jest --testPathPattern kyc`.",
+    "npm run type-check passes with no errors."
+  ],
+  "verification": [
+    "npm run type-check  — must produce zero TypeScript errors",
+    "npx jest --testPathPattern kyc --forceExit  — all existing KYC tests pass",
+    "npx jest --testPathPattern notification --forceExit  — existing notification tests still pass"
+  ],
+  "blocked_reason": null,
+  "findings": "NotificationType enum now has KYC_STATUS_CHANGE and SECONDARY_MARKET_SOLD values. KycService constructor accepts optional fourth param notificationService?: NotificationService and fires createNotification after processWebhook commits. src/index.ts passes notificationService to KycService. Pre-existing failure in tests/notifications-endpoint.test.ts (SQLite3 package not installed in env) is unrelated to these changes and was failing before. FEAT-002 can rely on KYC_STATUS_CHANGE and SECONDARY_MARKET_SOLD being present in the enum."
+}

.agents/tasks/task-notification-service-564/features/FEAT-002.json

@@ -0,0 +1,28 @@
+{
+  "id": "FEAT-002",
+  "type": "feat",
+  "description": "Wire secondary-market sold notifications into SecondaryMarketService. Adds optional notificationService dependency to SecondaryMarketService and its factory, calls createNotification with SECONDARY_MARKET_SOLD after a listing is fully sold in buyListing(), and passes notificationService in src/index.ts. Depends on FEAT-001 (SECONDARY_MARKET_SOLD enum value must exist first).",
+  "status": "completed",
+  "steps": [
+    "1. In src/services/secondary-market.service.ts, add a type import for NotificationService: `import type { NotificationService } from './notification.service'` and add NotificationType, ListingStatus to the existing enums import from '../types/enums' (ListingStatus is already imported — just ensure NotificationType is also imported).",
+    "2. In the SecondaryMarketService constructor, add an optional second parameter: `constructor(private readonly dataSource: DataSource, private readonly notificationService?: NotificationService)`.",
+    "3. In SecondaryMarketService.buyListing(), the method returns inside a `this.dataSource.transaction(...)` callback. To notify after the transaction, change the approach: capture the result of the transaction in a local variable, then fire the notification after the transaction resolves. Specifically: store the transaction result (keep existing BuyListingResult shape intact) and also track `soldListingId`, `soldSellerId`, and a `wasSold` boolean from inside the transaction callback. After `await this.dataSource.transaction(...)` resolves, if wasSold and this.notificationService is defined, call createNotification in a try/catch. Use `soldSellerId ?? soldListing.sellerWallet` as the userId (SecondaryListing.sellerId is the TypeORM User FK, nullable; sellerWallet is always present). Use NotificationType.SECONDARY_MARKET_SOLD, title 'Listing Sold', message 'Your listing for an invoice fraction has been fully purchased.', data { listingId, buyerWallet, quantity, totalPrice }. Catch any error and call logger.warn('secondary.notification.failed', { listing_id, error }).",
+    "4. In the factory function createSecondaryMarketService at the bottom of the file, update its signature to accept an optional second parameter and forward it: `export function createSecondaryMarketService(dataSource: DataSource, notificationService?: NotificationService): SecondaryMarketService { return new SecondaryMarketService(dataSource, notificationService); }`",
+    "5. In src/index.ts, update the factory call from `createSecondaryMarketService(dataSource)` to `createSecondaryMarketService(dataSource, notificationService)`."
+  ],
+  "acceptance_criteria": [
+    "SecondaryMarketService constructor accepts optional second parameter of type NotificationService.",
+    "After buyListing() fully sells a listing (sets status to ListingStatus.SOLD), createNotification is called with the seller's userId, SECONDARY_MARKET_SOLD type, and metadata.",
+    "If createNotification throws, buyListing still returns the BuyListingResult successfully.",
+    "Partial sales (quantity < listing.quantity) do NOT trigger a notification.",
+    "All existing secondary market tests pass without modification.",
+    "npm run type-check passes with no errors."
+  ],
+  "verification": [
+    "npm run type-check  — must produce zero TypeScript errors",
+    "npx jest --testPathPattern secondary-market --forceExit  — all existing secondary market tests pass",
+    "npm run test:ci  — full suite passes with no regressions"
+  ],
+  "blocked_reason": null,
+  "findings": "All 5 steps implemented. NotificationType and NotificationService import added to secondary-market.service.ts. SecondaryMarketService constructor updated with optional notificationService param. buyListing() refactored to capture sold state variables from within the transaction and fire createNotification after the transaction resolves. Notification is wrapped in try/catch and logs warnings on failure. Factory function updated to accept and forward notificationService. src/index.ts updated to pass notificationService to createSecondaryMarketService. Type-check passes with zero errors. Pre-existing CI failures (24 test suites) are unrelated to this change — all caused by a zod v4 module resolution issue."
+}

.env.example

@@ -10,11 +10,32 @@ CORS_ALLOW_CREDENTIALS=true
 HTTP_BODY_SIZE_LIMIT=1mb
 HTTP_SHUTDOWN_TIMEOUT_MS=15000
 
-# Rate Limiting
+# Redis
+REDIS_URL=redis://localhost:6379
+
+# Rate Limiting (Global and Sensitive Endpoints)
 RATE_LIMIT_ENABLED=true
 RATE_LIMIT_WINDOW_MS=60000
 RATE_LIMIT_MAX=100
 
+# Rate Limiting - Auth Endpoints (per-IP and per-wallet)
+RATE_LIMIT_AUTH_IP_WINDOW_MS=60000
+RATE_LIMIT_AUTH_IP_MAX=20
+RATE_LIMIT_AUTH_WALLET_WINDOW_MS=60000
+RATE_LIMIT_AUTH_WALLET_MAX=10
+
+# Rate Limiting - Invest Endpoints (per-IP and per-wallet)
+RATE_LIMIT_INVEST_IP_WINDOW_MS=60000
+RATE_LIMIT_INVEST_IP_MAX=30
+RATE_LIMIT_INVEST_WALLET_WINDOW_MS=60000
+RATE_LIMIT_INVEST_WALLET_MAX=10
+
+# Rate Limiting - Invoice Submission Endpoints (per-IP and per-wallet)
+RATE_LIMIT_INVOICE_SUBMIT_IP_WINDOW_MS=60000
+RATE_LIMIT_INVOICE_SUBMIT_IP_MAX=30
+RATE_LIMIT_INVOICE_SUBMIT_WALLET_WINDOW_MS=60000
+RATE_LIMIT_INVOICE_SUBMIT_WALLET_MAX=10
+
 # Database
 DATABASE_URL=postgresql://user:password@localhost:5432/stellarsettle
 
@@ -32,6 +53,12 @@ PLATFORM_SECRET_KEY=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 # Smart Contracts
 ESCROW_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 TOKEN_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+STELLAR_RPC_URL=https://soroban-testnet.stellar.org
+SOROBAN_INDEXER_CONTRACT_IDS=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ONBOARDING_BONUS_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+ONBOARDING_BONUS_POOL_STORAGE_KEY=pool_balance
+NOTIFICATION_SERVICE_URL=http://localhost:3001/notifications
+# NOTIFICATION_SERVICE_TOKEN=
 
 # IPFS
 IPFS_API_URL=https://api.pinata.cloud
@@ -46,6 +73,9 @@ JWT_SECRET=your-super-secret-jwt-key
 JWT_EXPIRES_IN=15m
 AUTH_CHALLENGE_TTL_MS=300000
 
+# Admin JWT (for admin endpoints, separate from user JWT)
+ADMIN_JWT_SECRET=your-admin-jwt-secret
+
 # Observability
 METRICS_ENABLED=true
 
@@ -61,4 +91,23 @@ SENDGRID_API_KEY=SG.xxxxxxxxxxxxx
 FROM_EMAIL=noreply@stellarsettle.com
 
 #dev-secret-key
-ADMIN_API_KEY=dev-secret-key
+ADMIN_API_KEY=dev-secret-key
+# Investor accreditation terms version (issue #473). Bump to force re-acknowledgement.
+TERMS_VERSION=1
+
+# IP Whitelist for admin routes (comma-separated CIDR blocks)
+ADMIN_IP_WHITELIST=127.0.0.1,::1
+
+# Caching (Redis)
+REDIS_URL=redis://localhost:6379
+CACHE_ENABLED=true
+CACHE_TTL_INVOICES_LIST=30
+CACHE_TTL_INVOICE_DETAIL=60
+
+# Webhooks
+KYC_WEBHOOK_SECRET=your-kyc-webhook-secret
+WEBHOOK_SECRET=your-shared-webhook-secret
+
+# Ratings Leaderboard
+# Minimum number of ratings a key must have before it qualifies for the leaderboard
+LEADERBOARD_MIN_RATING_COUNT=5

.eslintrc.cjs

@@ -18,6 +18,7 @@ module.exports = {
   ],
   ignorePatterns: ["dist/", "node_modules/", "coverage/", "*.cjs"],
   rules: {
+    "no-useless-escape": "off",
     "@typescript-eslint/no-unused-vars": [
       "error",
       {

.github/workflows/api-cy.yml

@@ -44,14 +44,27 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
+      - name: OpenAPI Schema Drift Check
+        run: npm run verify:openapi
+
+      - name: Database Migration Safety Check
+        run: bash scripts/test-migrations.sh
+
       - name: Run linter
         run: npm run lint
 
       - name: Type check
         run: npm run type-check
 
-      - name: Run tests
-        run: npm test
+      - name: Run tests with coverage
+        run: npm test -- --coverage
 
       - name: Build
         run: npm run build
+
+      - name: Upload coverage reports
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: coverage-report
+          path: coverage/

.github/workflows/ci.yml

@@ -0,0 +1,110 @@
+name: API CI
+
+on:
+  pull_request:
+    branches: [dev]
+  push:
+    branches: [dev]
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci
+        timeout-minutes: 10
+      - name: Run linter
+        run: npm run lint
+        timeout-minutes: 5
+
+  type-check:
+    name: Type Check
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci
+        timeout-minutes: 10
+      - name: Run type check
+        run: npm run type-check
+        timeout-minutes: 5
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci
+        timeout-minutes: 10
+      - name: Build project
+        run: npm run build
+        timeout-minutes: 5
+
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    services:
+      postgres:
+        image: postgres:15-alpine
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: password
+          POSTGRES_DB: stellarsettle_test
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres -d stellarsettle_test"
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+          --health-start-period 10s
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+      - name: Install dependencies
+        run: npm ci
+        timeout-minutes: 10
+      - name: Wait for PostgreSQL
+        run: |
+          for i in {1..30}; do
+            if pg_isready -h localhost -p 5432 -U postgres; then
+              echo "PostgreSQL is ready"
+              exit 0
+            fi
+            echo "Waiting for PostgreSQL... ($i/30)"
+            sleep 2
+          done
+          echo "PostgreSQL did not become ready in time"
+          exit 1
+        timeout-minutes: 2
+      - name: Run tests
+        run: npm test -- --runInBand
+        timeout-minutes: 10
+        env:
+          DATABASE_URL: postgresql://postgres:password@localhost:5432/stellarsettle_test

.github/workflows/commitlint.yml

@@ -3,7 +3,7 @@ name: Commitlint
 
 on:
   pull_request:
-    branches: [main, develop]
+    branches: [main, dev]
 
 jobs:
   commitlint: