fix: unbounded queries, findFirst determinism, sequence retry, PII encryption guard (#205, #206, #207, #208) (#369)

- #205: findByVendor and findByBuyer now accept optional cursor/take params and apply orderBy:createdAt desc — prevents unbounded heap allocation on large result sets; callers that omit pagination get the first 20 records
- #206: findByVendorAndItem adds orderBy:createdAt asc for deterministic results; schema.prisma replaces @@index([vendorAddress, itemRef]) with @@unique to enforce at the DB layer that duplicate item refs per vendor are rejected
- #207: StellarServer interface gains loadAccount(); submitAutoRelease now accepts sourceAddress and calls loadAccount before every attempt so each retry builds a fresh transaction with the current sequence number — fixes the root cause of tx_bad_seq retry loops; AUTO_RELEASE_SOURCE_ADDRESS env var wires the source address from the worker
- #208: assertEncryptedContact() guard added to PrismaService escrow.create and escrow.update — throws if buyerContactEmail or buyerContactPhone is non-null and does not match the AES-256-GCM iv:tag:ciphertext hex format; SECURITY.md documents the encryption scheme, key rotation procedure, and regulatory context

Author: Gbangbolaoluwagbemiga

SECURITY.md

@@ -66,6 +66,47 @@ Out of scope:
 
 ## Security Controls
 
+### Buyer Contact Encryption (PII at rest)
+
+`buyerContactEmail` and `buyerContactPhone` are classified as Personal Identifiable Information (PII) and **must never be written to the database in plaintext**.
+
+#### Encryption scheme
+
+| Property | Value |
+|----------|-------|
+| Algorithm | AES-256-GCM |
+| Key size | 256 bits (32 bytes) |
+| IV size | 96 bits (12 bytes), randomly generated per call |
+| Auth tag | 128 bits (16 bytes) |
+| Storage format | `<iv_hex>:<auth_tag_hex>:<ciphertext_hex>` (colon-separated hex) |
+| Key source | `CONTACT_ENCRYPTION_KEY` env variable (64 hex chars = 32 bytes) |
+
+Encrypting the same plaintext twice produces different ciphertext — each call generates a fresh IV, preventing correlation attacks.
+
+#### Code path
+
+```
+EscrowController → EscrowService.updateBuyerContact()
+  → encryptContact()           [contact-encryption.util.ts]
+  → EscrowRepository.saveBuyerContact()
+  → PrismaService.escrow.update()  [validates ciphertext format before write]
+```
+
+#### Defence-in-depth guard
+
+`PrismaService.escrow.create` and `escrow.update` both call `assertEncryptedContact()` before any write. If either field is provided without matching the expected `iv:tag:ciphertext` hex format, an exception is thrown and the write is aborted. This makes plaintext storage impossible by construction even if a new code path bypasses `encryptContact()`.
+
+#### Key rotation
+
+1. Generate a new 32-byte key: `openssl rand -hex 32`
+2. Re-encrypt all non-null `buyerContactEmail`/`buyerContactPhone` rows using the new key.
+3. Update `CONTACT_ENCRYPTION_KEY` in the secret store and restart the service.
+4. Verify no plaintext remains by checking that all stored values match the `iv:tag:ciphertext` format.
+
+#### Regulatory context
+
+This control supports compliance with NDPR (Nigeria Data Protection Regulation), GDPR (Article 32 — appropriate technical measures), and similar frameworks requiring encryption of personal data at rest.
+
 ### Environment Variables
 
 | Variable | Requirement |
@@ -74,6 +115,8 @@ Out of scope:
 | `ADMIN_ADDRESS` | Valid Stellar public key (G...) |
 | `DATABASE_URL` | TLS/SSL required in production |
 | `STELLAR_WEBHOOK_SECRET` | Required in production for webhook HMAC verification |
+| `CONTACT_ENCRYPTION_KEY` | Exactly 64 hex characters (32 bytes); rotate annually or on suspected compromise |
+| `AUTO_RELEASE_SOURCE_ADDRESS` | Stellar public key of the auto-release signing account |
 
 Never commit `.env` files. Use environment-specific secret management (Vault, AWS Secrets Manager, etc.).
 

prisma/schema.prisma

@@ -53,7 +53,7 @@ model Escrow {
   @@index([vendorAddress])
   @@index([buyerAddress])
   @@index([vendorAddress, state])
-  @@index([vendorAddress, itemRef])
+  @@unique([vendorAddress, itemRef])
   @@index([state, trackingId])
   @@index([state, createdAt])
   @@index([state, deliveredAt])

src/escrow/escrow.repository.spec.ts

@@ -1,5 +1,9 @@
 import { EscrowRepository } from './escrow.repository';
 import { PrismaService } from '../prisma/prisma.service';
+import { encryptContact } from '../common/sanitization/contact-encryption.util';
+
+// Required by the encryption util
+process.env.CONTACT_ENCRYPTION_KEY = 'a'.repeat(64);
 
 function makeDto() {
   return {
@@ -56,6 +60,103 @@ describe('EscrowRepository', () => {
     });
   });
 
+  // ── #205: cursor-based pagination ─────────────────────────────────────────
+  describe('findByVendor() — pagination (#205)', () => {
+    beforeEach(async () => {
+      await repo.create({ ...makeDto(), itemRef: 'A' }, 'v-page');
+      await repo.create({ ...makeDto(), itemRef: 'B' }, 'v-page');
+      await repo.create({ ...makeDto(), itemRef: 'C' }, 'v-page');
+    });
+
+    it('returns up to `take` records for the first page', async () => {
+      const results = await repo.findByVendor('v-page', undefined, 2);
+      expect(results).toHaveLength(2);
+    });
+
+    it('returns remaining records after a cursor', async () => {
+      const first = await repo.findByVendor('v-page', undefined, 2);
+      const second = await repo.findByVendor('v-page', first[first.length - 1].id, 10);
+      expect(second.length).toBeGreaterThanOrEqual(1);
+      expect(second.map((e) => e.id)).not.toContain(first[0].id);
+    });
+
+    it('returns an empty array when no more records exist after cursor', async () => {
+      const all = await repo.findByVendor('v-page', undefined, 100);
+      const last = all[all.length - 1];
+      const next = await repo.findByVendor('v-page', last.id, 10);
+      expect(next).toHaveLength(0);
+    });
+  });
+
+  describe('findByBuyer() — pagination (#205)', () => {
+    beforeEach(async () => {
+      await repo.create({ ...makeDto(), itemRef: 'P', buyerAddress: 'b-page' }, 'v1');
+      await repo.create({ ...makeDto(), itemRef: 'Q', buyerAddress: 'b-page' }, 'v1');
+    });
+
+    it('returns up to `take` records', async () => {
+      const results = await repo.findByBuyer('b-page', undefined, 1);
+      expect(results).toHaveLength(1);
+    });
+
+    it('uses default take of 20 when not specified', async () => {
+      const results = await repo.findByBuyer('b-page');
+      expect(results.length).toBeLessThanOrEqual(20);
+    });
+  });
+
+  // ── #206: findFirst instead of findMany + index ────────────────────────────
+  describe('findByVendorAndItem() — findFirst determinism (#206)', () => {
+    it('returns the earliest record when multiple share the same (vendorAddress, itemRef)', async () => {
+      const first = await repo.create({ ...makeDto(), itemRef: 'DUP' }, 'v-dup');
+      await repo.create({ ...makeDto(), itemRef: 'DUP' }, 'v-dup');
+      const found = await repo.findByVendorAndItem('v-dup', 'DUP');
+      expect(found?.id).toBe(first.id);
+    });
+  });
+
+  // ── #208: plaintext buyer contact rejected by prisma guard ────────────────
+  describe('saveBuyerContact() — encryption guard (#208)', () => {
+    it('stores encrypted contact without throwing', async () => {
+      const escrow = await repo.create(makeDto(), 'v-enc');
+      const encEmail = encryptContact('test@example.com');
+      const encPhone = encryptContact('+2348001234567');
+      await expect(
+        repo.saveBuyerContact(escrow.id, encEmail, encPhone),
+      ).resolves.toBeDefined();
+    });
+
+    it('throws when plaintext email is passed directly to the repository', async () => {
+      const escrow = await repo.create(makeDto(), 'v-enc2');
+      await expect(
+        repo.saveBuyerContact(escrow.id, 'plaintext@example.com', null),
+      ).rejects.toThrow(/Security violation.*buyerContactEmail/);
+    });
+
+    it('throws when plaintext phone is passed directly to the repository', async () => {
+      const escrow = await repo.create(makeDto(), 'v-enc3');
+      await expect(
+        repo.saveBuyerContact(escrow.id, null, '+2348001234567'),
+      ).rejects.toThrow(/Security violation.*buyerContactPhone/);
+    });
+
+    it('allows null values (contact not provided)', async () => {
+      const escrow = await repo.create(makeDto(), 'v-enc4');
+      await expect(
+        repo.saveBuyerContact(escrow.id, null, null),
+      ).resolves.toBeDefined();
+    });
+
+    it('stored value differs from plaintext input', async () => {
+      const escrow = await repo.create(makeDto(), 'v-enc5');
+      const plain = 'secret@test.com';
+      const enc = encryptContact(plain);
+      const updated = await repo.saveBuyerContact(escrow.id, enc, null);
+      expect(updated.buyerContactEmail).not.toBe(plain);
+      expect(updated.buyerContactEmail).toBe(enc);
+    });
+  });
+
   describe('findVendorEscrows()', () => {
     beforeEach(async () => {
       await repo.create({ ...makeDto(), amount: 300, itemRef: 'A' }, 'v1');

src/escrow/escrow.repository.ts

@@ -44,13 +44,16 @@ export class EscrowRepository {
   /**
    * Finds the first escrow matching both vendorAddress and itemRef,
    * used to detect duplicate submissions for the same item reference.
+   * Uses findFirst (LIMIT 1) rather than findMany so only one row is
+   * loaded; orderBy makes the result deterministic when duplicates exist.
    */
   findByVendorAndItem(
     vendorAddress: string,
     itemRef: string,
   ): Promise<EscrowRecord | null> {
     return this.prisma.escrow.findFirst({
       where: { vendorAddress, itemRef },
+      orderBy: { createdAt: 'asc' },
     });
   }
 
@@ -67,14 +70,40 @@ export class EscrowRepository {
     return record;
   }
 
-  /** Returns all escrows belonging to the given vendor address. */
-  findByVendor(vendorAddress: string): Promise<EscrowRecord[]> {
-    return this.prisma.escrow.findMany({ where: { vendorAddress } });
+  /**
+   * Returns a cursor-paginated slice of escrows for the given vendor,
+   * ordered newest-first. Pass `cursor` (an escrow ID) to get the page
+   * after that record; omit it for the first page.
+   */
+  findByVendor(
+    vendorAddress: string,
+    cursor?: string,
+    take = 20,
+  ): Promise<EscrowRecord[]> {
+    return this.prisma.escrow.findMany({
+      where: { vendorAddress },
+      orderBy: { createdAt: 'desc' },
+      take,
+      ...(cursor ? { cursor: { id: cursor }, skip: 1 } : {}),
+    });
   }
 
-  /** Returns all escrows belonging to the given buyer address. */
-  findByBuyer(buyerAddress: string): Promise<EscrowRecord[]> {
-    return this.prisma.escrow.findMany({ where: { buyerAddress } });
+  /**
+   * Returns a cursor-paginated slice of escrows for the given buyer,
+   * ordered newest-first. Pass `cursor` (an escrow ID) to get the page
+   * after that record; omit it for the first page.
+   */
+  findByBuyer(
+    buyerAddress: string,
+    cursor?: string,
+    take = 20,
+  ): Promise<EscrowRecord[]> {
+    return this.prisma.escrow.findMany({
+      where: { buyerAddress },
+      orderBy: { createdAt: 'desc' },
+      take,
+      ...(cursor ? { cursor: { id: cursor }, skip: 1 } : {}),
+    });
   }
 
   /** Updates the escrow state and invalidates its cache entry. */

src/prisma/prisma.service.ts

@@ -1,5 +1,24 @@
 import { Injectable, Logger, OnModuleDestroy } from '@nestjs/common';
 
+// AES-256-GCM ciphertext produced by contact-encryption.util: iv:authTag:ciphertext
+// IV = 12 bytes (24 hex), tag = 16 bytes (32 hex), ciphertext = 1+ hex chars.
+const ENCRYPTED_CONTACT_RE = /^[0-9a-f]{24}:[0-9a-f]{32}:[0-9a-f]+$/i;
+
+/**
+ * Guards against plaintext writes to buyer PII fields.
+ * Throws at the repository layer if a non-null value doesn't match the
+ * expected AES-256-GCM ciphertext format produced by encryptContact().
+ */
+function assertEncryptedContact(field: string, value: string | null | undefined): void {
+  if (value == null) return;
+  if (!ENCRYPTED_CONTACT_RE.test(value)) {
+    throw new Error(
+      `Security violation: ${field} must be encrypted before persistence. ` +
+      `Use encryptContact() from contact-encryption.util before writing to the database.`,
+    );
+  }
+}
+
 export type EscrowState =
   | 'CREATED'
   | 'FUNDED'
@@ -364,6 +383,8 @@ export class PrismaService implements OnModuleDestroy {
 
   escrow = {
     create: ({ data }: { data: EscrowCreateInput }): Promise<EscrowRecord> => {
+      assertEncryptedContact('buyerContactEmail', data.buyerContactEmail);
+      assertEncryptedContact('buyerContactPhone', data.buyerContactPhone);
       const now = new Date();
       const escrow: EscrowRecord = {
         ...data,
@@ -511,6 +532,8 @@ export class PrismaService implements OnModuleDestroy {
       where: { id: string };
       data: EscrowUpdateInput;
     }): Promise<EscrowRecord> => {
+      assertEncryptedContact('buyerContactEmail', data.buyerContactEmail);
+      assertEncryptedContact('buyerContactPhone', data.buyerContactPhone);
       const existing = this.escrows.get(where.id);
       if (!existing) {
         throw new Error(`Escrow ${where.id} not found`);

src/stellar/contract.service.ts

@@ -4,6 +4,8 @@ import { STELLAR_SERVER } from './stellar.tokens';
 import { DEFAULT_AUTO_RELEASE_MAX_RETRIES } from './contract.constants';
 
 interface StellarServer {
+  /** Loads the current account state (including sequence number) from Horizon. */
+  loadAccount(sourceAddress: string): Promise<{ sequence: string }>;
   submitTransaction(transaction: Record<string, unknown>): Promise<{
     hash?: string;
     status?: string;
@@ -41,9 +43,20 @@ export class ContractService {
     return result.hash;
   }
 
-  /** Submits an auto-release transaction, retrying sequence errors up to the limit. */
+  /**
+   * Submits an auto-release transaction, retrying on Stellar sequence errors.
+   *
+   * On each attempt the source account is re-fetched from Horizon so the
+   * transaction is rebuilt with the current sequence number — a stale sequence
+   * embedded in the XDR is the root cause of every retry failure on tx_bad_seq.
+   *
+   * @param escrowId      Trust-Link escrow identifier embedded in the contract call.
+   * @param sourceAddress Stellar address of the auto-release signing account.
+   * @param maxRetries    Maximum number of additional attempts after the first failure.
+   */
   async submitAutoRelease(
     escrowId: string,
+    sourceAddress: string,
     maxRetries = DEFAULT_AUTO_RELEASE_MAX_RETRIES,
   ): Promise<string> {
     if (!this.server) {
@@ -52,10 +65,17 @@ export class ContractService {
 
     let attempt = 0;
     while (attempt <= maxRetries) {
+      // Re-fetch the account before every attempt so the transaction is built
+      // with the current sequence number. Without this, a sequence error on
+      // attempt N causes attempt N+1 to replay the same stale XDR and fail again.
+      const account = await this.server.loadAccount(sourceAddress);
+
       try {
         const result = await this.server.submitTransaction({
           operation: 'autoRelease',
           escrowId,
+          sourceAddress,
+          sequence: account.sequence,
         });
 
         if (result.status === 'ERROR' || result.resultXdr === 'TxFailed') {

src/workers/auto-release.worker.ts

@@ -10,6 +10,10 @@ import { ContractService } from '../stellar/contract.service';
 
 const EVERY_5_MINUTES = 5 * 60 * 1000;
 
+// Stellar address of the auto-release signing account. Must be set in production.
+const AUTO_RELEASE_SOURCE =
+  process.env.AUTO_RELEASE_SOURCE_ADDRESS ?? 'GAUTORELEASE000000000000000000000000000000000000000000000';
+
 @Injectable()
 export class AutoReleaseWorker implements OnModuleInit, OnApplicationShutdown {
   private readonly logger = new Logger(AutoReleaseWorker.name);
@@ -56,6 +60,7 @@ export class AutoReleaseWorker implements OnModuleInit, OnApplicationShutdown {
 
           const txHash = await this.contractService.submitAutoRelease(
             escrow.id,
+            AUTO_RELEASE_SOURCE,
           );
           await this.escrowRepository.markAutoReleaseCompleted(
             escrow.id,