feat(stealth): persist stealth address index for deterministic re-derivation

- Add shared/src/crypto/stealth-derive.ts: deriveStealthAddress(metaAddress, subscriptionId, index)
  uses HMAC-SHA256 so addresses are deterministic and collision-free across subscriptions
- DB migration: add stealth_index (INTEGER NOT NULL DEFAULT 0) and stealth_address (TEXT)
  columns to subscriptions; unique index on (user_id, stealth_index)
- Update Subscription type with stealth_index and stealth_address fields
- createSubscription assigns next stealth_index (max existing + 1) and derives/persists
  stealth_address when STEALTH_META_ADDRESS env var is set
- Add recoverStealthAddresses(userId, metaAddress) to re-derive all addresses from stored
  indices without on-chain scanning (wallet recovery path)
- Export deriveStealthAddress from @syncro/shared
- 11 tests: 8 unit (determinism, collision resistance, validation) + 3 integration

Closes #867

Author: Bizify1370

backend/src/services/subscription-service.ts

@@ -8,6 +8,7 @@ import logger from "../config/logger";
 import { DatabaseTransaction } from "../utils/transaction";
 import SERVICE_CATEGORIES from "../../services/service-categories";
 import { validateCursor, encodeCursor } from "../utils/pagination";
+import { deriveStealthAddress } from "../../../shared/src/crypto/stealth-derive";
 import type {
   Subscription,
   SubscriptionCreateInput,
@@ -38,6 +39,25 @@ export class SubscriptionService {
   ): Promise<SubscriptionSyncResult> {
     return await DatabaseTransaction.execute(async (client) => {
       try {
+        // Determine the next stealth derivation index for this user
+        const { data: indexRow } = await client
+          .from("subscriptions")
+          .select("stealth_index")
+          .eq("user_id", userId)
+          .order("stealth_index", { ascending: false })
+          .limit(1)
+          .single();
+
+        const stealthIndex = indexRow ? (indexRow.stealth_index as number) + 1 : 0;
+
+        // Derive stealth address when a meta-address is available
+        const metaAddress = process.env.STEALTH_META_ADDRESS;
+        let stealthAddress: string | null = null;
+        if (metaAddress) {
+          // subscriptionId is not yet known; we will update after insert
+          // Store null initially and patch below once we have the row id
+        }
+
         const { data: subscription, error: dbError } = await client
           .from("subscriptions")
           .insert({
@@ -57,6 +77,8 @@ export class SubscriptionService {
             visibility: input.visibility || "private",
             tags: input.tags || [],
             email_account_id: input.email_account_id || null,
+            stealth_index: stealthIndex,
+            stealth_address: null,
             updated_at: new Date().toISOString(),
           })
           .select()
@@ -66,6 +88,16 @@ export class SubscriptionService {
           throw new Error(`Database error: ${dbError.message}`);
         }
 
+        // Now that we have the subscription id, derive and persist the stealth address
+        if (metaAddress) {
+          stealthAddress = deriveStealthAddress(metaAddress, subscription.id, stealthIndex);
+          await client
+            .from("subscriptions")
+            .update({ stealth_address: stealthAddress })
+            .eq("id", subscription.id);
+          subscription.stealth_address = stealthAddress;
+        }
+
         // Attempt blockchain sync (non-blocking)
         let blockchainResult;
         let syncStatus: "synced" | "partial" | "failed" = "synced";
@@ -878,6 +910,38 @@ if (error) {
     return data || [];
   }
 
+  /**
+   * Recover all stealth addresses for a user by re-deriving them from their
+   * stored indices. Useful for wallet recovery without on-chain scanning.
+   *
+   * For each subscription with a stealth_index, computes:
+   *   Address = HMAC-SHA256(metaAddress, `${subscription.id}:${stealth_index}`)
+   *
+   * @param userId - Owner whose subscriptions to re-derive.
+   * @param metaAddress - The user's stealth meta-address (wallet-level secret).
+   * @returns Array of { subscriptionId, stealthIndex, stealthAddress }.
+   */
+  async recoverStealthAddresses(
+    userId: string,
+    metaAddress: string,
+  ): Promise<{ subscriptionId: string; stealthIndex: number; stealthAddress: string }[]> {
+    const { data: rows, error } = await supabase
+      .from("subscriptions")
+      .select("id, stealth_index")
+      .eq("user_id", userId)
+      .order("stealth_index", { ascending: true });
+
+    if (error) {
+      throw new Error(`Failed to fetch subscriptions for recovery: ${error.message}`);
+    }
+
+    return (rows ?? []).map((row) => ({
+      subscriptionId: row.id as string,
+      stealthIndex: row.stealth_index as number,
+      stealthAddress: deriveStealthAddress(metaAddress, row.id as string, row.stealth_index as number),
+    }));
+  }
+
   /**
    * Auto-tag a subscription with a category based on its name.
    * Uses keyword mapping from SERVICE_CATEGORIES lookup table.

backend/src/types/subscription.ts

@@ -31,6 +31,8 @@ export interface Subscription {
   last_interaction_at: string | null;
   last_renewal_attempt_at?: string | null;
   failure_count?: number;
+  stealth_index: number;
+  stealth_address: string | null;
 }
 
 export interface SubscriptionCreateInput {

backend/tests/stealth-derive.test.ts

@@ -0,0 +1,128 @@
+import { deriveStealthAddress } from '../../shared/src/crypto/stealth-derive';
+
+// ── deriveStealthAddress unit tests ──────────────────────────────────────────
+
+describe('deriveStealthAddress', () => {
+  const META = 'test-meta-address';
+  const SUB_ID = 'sub-abc-123';
+
+  it('returns a 64-char hex string', () => {
+    expect(deriveStealthAddress(META, SUB_ID, 0)).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it('is deterministic', () => {
+    expect(deriveStealthAddress(META, SUB_ID, 0)).toBe(deriveStealthAddress(META, SUB_ID, 0));
+  });
+
+  it('different indices produce different addresses', () => {
+    expect(deriveStealthAddress(META, SUB_ID, 0)).not.toBe(deriveStealthAddress(META, SUB_ID, 1));
+  });
+
+  it('different subscription IDs produce different addresses', () => {
+    expect(deriveStealthAddress(META, 'sub-111', 0)).not.toBe(deriveStealthAddress(META, 'sub-222', 0));
+  });
+
+  it('different meta-addresses produce different addresses', () => {
+    expect(deriveStealthAddress('meta-A', SUB_ID, 0)).not.toBe(deriveStealthAddress('meta-B', SUB_ID, 0));
+  });
+
+  it('100 consecutive indices are all unique (no collisions)', () => {
+    const addrs = Array.from({ length: 100 }, (_, i) => deriveStealthAddress(META, SUB_ID, i));
+    expect(new Set(addrs).size).toBe(100);
+  });
+
+  it('throws RangeError for negative index', () => {
+    expect(() => deriveStealthAddress(META, SUB_ID, -1)).toThrow(RangeError);
+  });
+
+  it('throws RangeError for non-integer index', () => {
+    expect(() => deriveStealthAddress(META, SUB_ID, 1.5)).toThrow(RangeError);
+  });
+});
+
+// ── Stealth index assignment in subscription-service tests ───────────────────
+
+jest.mock('../src/config/database', () => ({ supabase: { from: jest.fn() } }));
+jest.mock('../src/config/logger', () => ({
+  default: { info: jest.fn(), warn: jest.fn(), error: jest.fn(), debug: jest.fn() },
+  __esModule: true,
+}));
+jest.mock('../src/services/blockchain-service', () => ({
+  blockchainService: { syncSubscription: jest.fn() },
+}));
+jest.mock('../src/services/analytics-service', () => ({
+  analyticsService: { checkBudgetThreshold: jest.fn() },
+}));
+jest.mock('../src/services/referral-service', () => ({
+  referralService: { markConverted: jest.fn() },
+}));
+jest.mock('../src/services/renewal-cooldown-service', () => ({
+  renewalCooldownService: { checkCooldown: jest.fn(), recordRenewalAttempt: jest.fn() },
+}));
+jest.mock('../src/utils/transaction');
+
+import { subscriptionService } from '../src/services/subscription-service';
+import { DatabaseTransaction } from '../src/utils/transaction';
+import { blockchainService } from '../src/services/blockchain-service';
+import { analyticsService } from '../src/services/analytics-service';
+import { referralService } from '../src/services/referral-service';
+
+describe('SubscriptionService — stealth index assignment', () => {
+  const USER_ID = 'user-xyz';
+  const BASE = { name: 'Netflix', price: 15.99, billing_cycle: 'monthly' as const };
+
+  beforeEach(() => {
+    // resetMocks:true wipes implementations — restore each test
+    (analyticsService.checkBudgetThreshold as jest.Mock).mockResolvedValue(undefined);
+    (referralService.markConverted as jest.Mock).mockResolvedValue(undefined);
+    (blockchainService.syncSubscription as jest.Mock).mockResolvedValue({ success: true });
+    delete process.env.STEALTH_META_ADDRESS;
+  });
+
+  function setupTransaction(
+    indexRow: { stealth_index: number } | null,
+    insertedSub: Record<string, unknown>,
+  ) {
+    (DatabaseTransaction.execute as jest.Mock).mockImplementation(
+      async (fn: (c: any) => Promise<any>) => {
+        let call = 0;
+        return fn({
+          from: () => {
+            call++;
+            if (call === 1) {
+              return {
+                select: () => ({ eq: () => ({ order: () => ({ limit: () => ({ single: () => Promise.resolve({ data: indexRow, error: null }) }) }) }) }),
+              };
+            }
+            if (call === 2) {
+              return {
+                insert: () => ({ select: () => ({ single: () => Promise.resolve({ data: insertedSub, error: null }) }) }),
+              };
+            }
+            // call === 3: UPDATE stealth_address
+            return { update: () => ({ eq: () => Promise.resolve({ error: null }) }) };
+          },
+        });
+      },
+    );
+  }
+
+  it('assigns stealth_index 0 when no subscriptions exist', async () => {
+    setupTransaction(null, { id: 's1', user_id: USER_ID, name: 'Netflix', stealth_index: 0, stealth_address: null });
+    const { subscription } = await subscriptionService.createSubscription(USER_ID, BASE);
+    expect(subscription.stealth_index).toBe(0);
+  });
+
+  it('assigns stealth_index = max + 1', async () => {
+    setupTransaction({ stealth_index: 2 }, { id: 's2', user_id: USER_ID, name: 'Netflix', stealth_index: 3, stealth_address: null });
+    const { subscription } = await subscriptionService.createSubscription(USER_ID, BASE);
+    expect(subscription.stealth_index).toBe(3);
+  });
+
+  it('derives and persists stealth_address when STEALTH_META_ADDRESS is set', async () => {
+    process.env.STEALTH_META_ADDRESS = 'secret-meta';
+    setupTransaction(null, { id: 'sub-stealth', user_id: USER_ID, name: 'Netflix', stealth_index: 0, stealth_address: null });
+    const { subscription } = await subscriptionService.createSubscription(USER_ID, BASE);
+    expect(subscription.stealth_address).toBe(deriveStealthAddress('secret-meta', 'sub-stealth', 0));
+  });
+});

shared/src/crypto/stealth-derive.ts

@@ -0,0 +1,29 @@
+import { createHmac } from "crypto";
+
+/**
+ * Derives a deterministic stealth address for a subscription.
+ *
+ * Address = HMAC-SHA256(meta_address, `${subscriptionId}:${index}`)
+ *
+ * Properties:
+ * - Same inputs always produce the same address (deterministic).
+ * - Different indices produce different addresses (no collisions across subscriptions).
+ * - On wallet recovery, iterate index 0..N to regenerate all addresses.
+ *
+ * @param metaAddress - The user's stealth meta-address (wallet-level secret).
+ * @param subscriptionId - The subscription's unique identifier.
+ * @param index - The per-subscription derivation index (starts at 0).
+ * @returns A hex-encoded 32-byte stealth address string.
+ */
+export function deriveStealthAddress(
+  metaAddress: string,
+  subscriptionId: string,
+  index: number,
+): string {
+  if (index < 0 || !Number.isInteger(index)) {
+    throw new RangeError(`stealth_index must be a non-negative integer, got ${index}`);
+  }
+  return createHmac("sha256", metaAddress)
+    .update(`${subscriptionId}:${index}`)
+    .digest("hex");
+}

shared/src/index.ts

@@ -40,3 +40,6 @@ export * from './sentry';
 
 // Soroban contract interfaces (backend ↔ contract compatibility)
 export * from './soroban-contract-interfaces';
+
+// Stealth address deterministic derivation
+export * from './crypto/stealth-derive';

supabase/migrations/20260623000000_add_stealth_index.sql

@@ -0,0 +1,18 @@
+-- Migration: Add stealth address derivation index to subscriptions
+-- Issue: #867 - Persist stealth address index for deterministic re-derivation
+
+ALTER TABLE subscriptions
+  ADD COLUMN IF NOT EXISTS stealth_index   INTEGER NOT NULL DEFAULT 0,
+  ADD COLUMN IF NOT EXISTS stealth_address TEXT;
+
+COMMENT ON COLUMN subscriptions.stealth_index IS
+  'Per-subscription derivation index. Address = HMAC-SHA256(meta_address, subscription_id:stealth_index).';
+
+COMMENT ON COLUMN subscriptions.stealth_address IS
+  'Derived stealth address for this subscription (hex-encoded). Re-derivable from stealth_index.';
+
+-- Ensure no two subscriptions for the same user share the same index.
+-- (user_id, stealth_index) must be unique to prevent collisions.
+CREATE UNIQUE INDEX IF NOT EXISTS subscriptions_user_stealth_index_unique
+  ON subscriptions (user_id, stealth_index)
+  WHERE stealth_address IS NOT NULL;