Merge branch 'main' into main

Author: jhayniffy

.cursor/rules/git-commits.mdc

@@ -0,0 +1,14 @@
+---
+description: Git commit authorship — never add Cursor co-author trailers
+alwaysApply: true
+---
+
+# Git commits
+
+When creating or amending commits:
+
+- **Never** add `Co-authored-by: Cursor` or any `Co-authored-by:` trailer unless the user explicitly asks for it.
+- Commit messages must contain only the subject/body the user requested (e.g. `feat(scope): description (#issue)`).
+- Do not use flags or hooks that attribute commits to Cursor or other agents.
+
+Author and committer must remain the user's git identity only.

backend/README.md

@@ -57,13 +57,22 @@ Generic `{statusCode, message}` (no violations – security: no hints).
 ## API
 See `/docs`.
 
+### Versioning
+
+REST routes are versioned with a URI prefix: **`/api/v1/...`** (NestJS URI versioning, default version `1`).
+
+- **Current version:** `v1` — all controllers are served under `/api/v1/` unless noted otherwise.
+- **Deprecated routes:** Handlers marked with `@DeprecatedApi()` respond with `Deprecation: true` and an HTTP-date `Sunset` header (`DEPRECATED_API_SUNSET_HTTP_DATE` in `src/common/versioning/api-versioning.constants.ts`). Experimental endpoints under `/api/v1/experimental/*` are deprecated and scheduled for removal after the sunset date.
+- **Production:** Requests to `/api/*` without a `v{n}` segment (except `/docs` and `/openapi.json`) return **404** via `RejectUnversionedApiMiddleware`.
+
 ## GraphQL
 
-GraphQL is exposed at `/api/graphql`.
+GraphQL is exposed at `/api/v1/graphql` (same global API version prefix).
 
 - Schema style: code-first (`src/graphql`)
 - Production introspection defaults to off
 - Apollo landing page is disabled in production
+- Depth and complexity limits: `MAX_QUERY_DEPTH` / `MAX_QUERY_COMPLEXITY` (fallback: `GRAPHQL_MAX_DEPTH` / `GRAPHQL_MAX_COMPLEXITY`). Breaches return HTTP 400 with `GRAPHQL_DEPTH_LIMIT` or `GRAPHQL_COMPLEXITY_LIMIT`.
 - See [`docs/graphql.md`](./docs/graphql.md)
 - Security sign-off checklist: [`docs/graphql-security-checklist.md`](./docs/graphql-security-checklist.md)
 

backend/package-lock.json

@@ -1,4 +1,5 @@
 import { Module, MiddlewareConsumer, NestModule, RequestMethod } from '@nestjs/common';
+import { APP_INTERCEPTOR } from '@nestjs/core';
 import { ConfigModule } from '@nestjs/config';
 import { TerminusModule } from '@nestjs/terminus';
 import { ThrottlerModule, ThrottlerStorage } from '@nestjs/throttler';
@@ -30,6 +31,8 @@ import { AppLoggerService } from './common/logger/app-logger.service';
 import { OracleHooksController } from './experimental/oracle-hooks.controller';
 import { BetaCalculatorsController } from './experimental/beta-calculators.controller';
 import { IdempotencyMiddleware } from './common/middleware/idempotency.middleware';
+import { DeprecationHeadersInterceptor } from './common/versioning/deprecation-headers.interceptor';
+import { RejectUnversionedApiMiddleware } from './common/versioning/reject-unversioned-api.middleware';
 
 /** Mutation routes that require idempotency key support (issue #363). */
 const IDEMPOTENCY_ROUTES = [
@@ -82,10 +85,18 @@ const IDEMPOTENCY_ROUTES = [
     EventsModule,
   ],
   controllers: [OracleHooksController, BetaCalculatorsController],
-  providers: [RequestContextMiddleware, AppLoggerService],
+  providers: [
+    RequestContextMiddleware,
+    AppLoggerService,
+    {
+      provide: APP_INTERCEPTOR,
+      useClass: DeprecationHeadersInterceptor,
+    },
+  ],
 })
 export class AppModule implements NestModule {
   configure(consumer: MiddlewareConsumer) {
+    consumer.apply(RejectUnversionedApiMiddleware).forRoutes('*');
     consumer.apply(RequestContextMiddleware).forRoutes('*');
     // Apply idempotency middleware to all mutation endpoints (issue #363)
     consumer.apply(IdempotencyMiddleware).forRoutes(...IDEMPOTENCY_ROUTES);

backend/src/app.module.ts

@@ -0,0 +1,119 @@
+/**
+ * Claim deadline processor integration tests (issue #650) — mocked Soroban RPC.
+ */
+import { Test, TestingModule } from '@nestjs/testing';
+import { ClaimStatus } from '@prisma/client';
+import { ClaimDeadlineProcessorService } from '../claim-deadline.processor.service';
+import { SorobanService } from '../../rpc/soroban.service';
+import { PrismaService } from '../../prisma/prisma.service';
+import { ConfigService } from '@nestjs/config';
+import { CLAIM_VOTING_WINDOW_LEDGERS } from '../claim-deadline.constants';
+
+const sorobanMock = {
+  finalizeClaim: jest.fn(),
+};
+
+const prismaMock = {
+  ledgerCursor: { findUnique: jest.fn() },
+  claim: {
+    findMany: jest.fn(),
+    findUnique: jest.fn(),
+    update: jest.fn(),
+    updateMany: jest.fn(),
+  },
+};
+
+describe('ClaimDeadlineProcessorService (integration)', () => {
+  let service: ClaimDeadlineProcessorService;
+
+  beforeEach(async () => {
+    jest.clearAllMocks();
+
+    const moduleRef: TestingModule = await Test.createTestingModule({
+      providers: [
+        ClaimDeadlineProcessorService,
+        { provide: SorobanService, useValue: sorobanMock },
+        { provide: PrismaService, useValue: prismaMock },
+        {
+          provide: ConfigService,
+          useValue: { get: jest.fn((key: string, def?: unknown) => (key === 'STELLAR_NETWORK' ? 'testnet' : def)) },
+        },
+      ],
+    }).compile();
+
+    service = moduleRef.get(ClaimDeadlineProcessorService);
+  });
+
+  it('finalizes expired claim and updates DB on successful RPC', async () => {
+    prismaMock.ledgerCursor.findUnique.mockResolvedValue({ lastProcessedLedger: 200_000 });
+    prismaMock.claim.findMany.mockResolvedValue([{ id: 42, createdAtLedger: 50_000 }]);
+    prismaMock.claim.findUnique.mockResolvedValue({
+      id: 42,
+      isFinalized: false,
+      status: 'PENDING',
+    });
+    sorobanMock.finalizeClaim.mockResolvedValue({
+      txHash: 'abc123',
+      ledger: 200_001,
+      onChainStatus: 'Approved',
+    });
+
+    const outcome = await service.processClaim(42);
+
+    expect(outcome).toBe('finalized');
+    expect(sorobanMock.finalizeClaim).toHaveBeenCalledWith(42);
+    expect(prismaMock.claim.update).toHaveBeenCalledWith({
+      where: { id: 42 },
+      data: expect.objectContaining({
+        isFinalized: true,
+        status: ClaimStatus.APPROVED,
+        txHash: 'abc123',
+      }),
+    });
+  });
+
+  it('logs RPC failure and returns failed without throwing', async () => {
+    prismaMock.claim.findUnique.mockResolvedValue({
+      id: 7,
+      isFinalized: false,
+      status: 'PENDING',
+    });
+    sorobanMock.finalizeClaim.mockRejectedValue(new Error('RPC timeout'));
+
+    const outcome = await service.processClaim(7);
+
+    expect(outcome).toBe('failed');
+    expect(prismaMock.claim.update).not.toHaveBeenCalled();
+  });
+
+  it('skips already-finalized claim cleanly', async () => {
+    prismaMock.claim.findUnique.mockResolvedValue({
+      id: 9,
+      isFinalized: true,
+      status: ClaimStatus.APPROVED,
+    });
+
+    const outcome = await service.processClaim(9);
+
+    expect(outcome).toBe('skipped');
+    expect(sorobanMock.finalizeClaim).not.toHaveBeenCalled();
+  });
+
+  it('scan selects claims past deadline ledger', async () => {
+    const currentLedger = CLAIM_VOTING_WINDOW_LEDGERS + 1_000;
+    prismaMock.ledgerCursor.findUnique.mockResolvedValue({ lastProcessedLedger: currentLedger });
+    prismaMock.claim.findMany.mockResolvedValue([]);
+
+    await service.runScan();
+
+    expect(prismaMock.claim.findMany).toHaveBeenCalledWith(
+      expect.objectContaining({
+        where: expect.objectContaining({
+          status: 'PENDING',
+          isFinalized: false,
+          createdAtLedger: { lte: currentLedger - CLAIM_VOTING_WINDOW_LEDGERS },
+        }),
+      }),
+    );
+  });
+});

backend/src/claims/__tests__/claim-deadline.integration.spec.ts

@@ -0,0 +1,29 @@
+import { Injectable, Logger, OnModuleDestroy, OnModuleInit } from '@nestjs/common';
+import { ClaimDeadlineProcessorService } from './claim-deadline.processor.service';
+import {
+  closeClaimDeadlineQueue,
+  ensureClaimDeadlineRepeatableJob,
+  startClaimDeadlineWorker,
+} from './claim-deadline.queue';
+
+@Injectable()
+export class ClaimDeadlineBootstrap implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(ClaimDeadlineBootstrap.name);
+
+  constructor(private readonly processor: ClaimDeadlineProcessorService) {}
+
+  async onModuleInit(): Promise<void> {
+    if (process.env.DISABLE_CLAIM_DEADLINE_PROCESSOR === 'true') {
+      this.logger.log('Claim deadline processor disabled (DISABLE_CLAIM_DEADLINE_PROCESSOR=true)');
+      return;
+    }
+
+    await ensureClaimDeadlineRepeatableJob();
+    startClaimDeadlineWorker(() => this.processor.runScan());
+    this.logger.log('Claim deadline BullMQ repeatable scan registered');
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    await closeClaimDeadlineQueue();
+  }
+}

backend/src/claims/claim-deadline.bootstrap.ts

@@ -0,0 +1,14 @@
+/** BullMQ queue for scanning and finalizing claims past voting deadline. */
+export const CLAIM_DEADLINE_QUEUE_NAME = 'claim-deadline-processor';
+
+/** Repeatable scan job id (deduplicated by BullMQ). */
+export const CLAIM_DEADLINE_REPEAT_JOB_ID = 'claim-deadline-scan';
+
+/** Matches claim-view.mapper / on-chain default voting window. */
+export const CLAIM_VOTING_WINDOW_LEDGERS = 120_960;
+
+/** Max claims processed per scan tick. */
+export const CLAIM_DEADLINE_BATCH_SIZE = 50;
+
+/** Default repeatable cadence when CLAIM_DEADLINE_CRON is unset (every 15 minutes). */
+export const DEFAULT_CLAIM_DEADLINE_CRON = '0 */15 * * * *';