feat: audit constraints on tags and gift_card_ledger tables (#660)

Author: Jerryvic911

backend/docs/ISSUE_660_IMPLEMENTATION.md

@@ -0,0 +1,123 @@
+# Issue #660 — Implementation Summary
+## [P1] Audit constraints on reminder, tag, and ledger tables
+
+**Date:** 2026-06-02  
+**Branch:** your branch name here  
+**Status:** Complete
+
+---
+
+## What this issue asked for
+
+The `tags`, `subscription_tags`, and `gift_card_ledger` tables had almost no
+safety rules (constraints). This meant the database could accept bad data like
+blank tag names, duplicate tag assignments, or gift card deductions that would
+make a user's balance go negative.
+
+This issue asked us to:
+1. Audit what constraints were missing
+2. Add those constraints via a migration
+3. Update the app to handle new constraint errors gracefully
+4. Write tests to prove everything works
+
+---
+## Files changed
+
+### 1. New migration
+`supabase/migrations/20260602000000_audit_constraints_tags_and_ledger.sql`
+
+Creates two brand new tables and adds missing constraints to an existing one.
+
+### 2. New utility
+`backend/src/utils/db-constraint-errors.ts`
+
+Maps Postgres constraint violation errors to typed HTTP errors so routes can
+return friendly 4xx responses instead of raw 500s.
+
+### 3. Updated route
+`backend/src/routes/tags.ts`
+
+- Added `parseDbError` to the `POST /api/tags` handler
+- Added `parseDbError` to the `POST /api/subscriptions/:id/tags` handler
+- Added `parseDbError` to the `DELETE /api/subscriptions/:id/tags/:tagId` handler
+- Fixed table name from `subscription_tag_assignments` to `subscription_tags`
+- Fixed table name from `subscription_tags` to `tags` in the GET and POST handlers
+
+### 4. Updated route
+`backend/src/routes/gift-card-ledger.ts`
+
+- Added `parseDbError` to the `POST /api/gift-card-ledger/top-up` handler
+
+### 5. New tests
+`backend/tests/db-constraint-errors.test.ts`
+
+13 unit tests covering every constraint mapping and the generic fallback.
+No database connection required — all tests use fake Postgres error objects.
+
+---
+
+## What the migration does
+
+### tags table (created from scratch)
+| Constraint | Rule |
+|---|---|
+| `tags_user_id_fkey` | user_id must refer to a real user |
+| `tags_user_id_name_lower_key` | no duplicate tag names per user (case-insensitive) |
+| `tags_name_length_check` | name must be 1–50 characters |
+| `tags_color_check` | color must be a valid hex code like #FF5733 or empty |
+
+### subscription_tags table (created from scratch)
+| Constraint | Rule |
+|---|---|
+| `subscription_tags_pkey` | composite primary key prevents duplicate tag assignments |
+| `subscription_tags_subscription_id_fkey` | subscription_id must refer to a real subscription |
+| `subscription_tags_tag_id_fkey` | tag_id must refer to a real tag |
+
+### gift_card_ledger table (updated)
+| Constraint | Rule |
+|---|---|
+| `gift_card_ledger_amount_check` | amount must never be zero |
+| `gift_card_ledger_type_check` | type expanded to include refund, adjustment, expiry |
+| `gift_card_ledger_type_amount_sign_check` | top_up/refund must be positive, deduction/expiry must be negative |
+| `gift_card_ledger_currency_check` | currency must be a valid 3-letter ISO code |
+| `gift_card_ledger_balance_after_check` | balance can never go below zero |
+| `gift_card_ledger_reference_id_user_idx` | reference_id must be unique per user |
+
+---
+
+## How to apply the migration
+
+```bash
+# From the repo root
+supabase db push
+```
+
+---
+
+## How to run the tests
+
+```bash
+# From the backend folder
+cd backend
+npx jest --testPathPattern="db-constraint-errors"
+```
+
+---
+
+## Security notes
+
+- No RLS policies were removed or weakened
+- All new tables have RLS enabled with owner-only policies
+- No new environment variables required
+- Migration is safe to re-run — all statements use IF NOT EXISTS guards
+
+---
+
+## PR checklist
+
+- [x] Constraint inventory produced
+- [x] Missing constraints added via migration
+- [x] Application code updated to handle new constraint errors
+- [x] Tests added and passing
+- [x] Documentation written
+- [x] No security regressions

backend/src/routes/gift-card-ledger.ts

@@ -4,6 +4,7 @@ import { authenticate, AuthenticatedRequest } from '../middleware/auth';
 import { giftCardLedgerService } from '../services/gift-card-ledger-service';
 import { validate } from '../middleware/validate';
 import { BadRequestError } from '../errors';
+import { parseDbError } from '../utils/db-constraint-errors';
 import { validateLimit } from '../utils/pagination';
 
 const router = Router();
@@ -44,9 +45,17 @@ router.get('/history', async (req: AuthenticatedRequest, res: Response) => {
 
 /** POST /api/gift-card-ledger/top-up */
 router.post('/top-up', validate(topUpSchema), async (req: AuthenticatedRequest, res: Response) => {
-  const { amount, description } = req.body;
-  const entry = await giftCardLedgerService.topUp(req.user!.id, amount, description);
-  res.status(201).json({ success: true, data: entry });
+  try {
+    const { amount, description } = req.body;
+    const entry = await giftCardLedgerService.topUp(req.user!.id, amount, description);
+    res.status(201).json({ success: true, data: entry });
+  } catch (err: any) {
+    const appError = parseDbError(err);
+    if (appError) {
+      return res.status(appError.status).json({ success: false, error: appError.message, field: appError.field });
+    }
+    throw err;
+  }
 });
 
 /** POST /api/gift-card-ledger/deduct */

backend/src/routes/tags.ts

@@ -16,6 +16,7 @@ import { supabase } from '../config/database';
 import logger from '../config/logger';
 import { createTagSchema, notesSchema, addTagSchema } from '../schemas/tag';
 import { uuidParamSchema } from '../schemas/common';
+import { parseDbError } from '../utils/db-constraint-errors';
 
 const router: express.Router = express.Router();
 router.use(authenticate);
@@ -64,8 +65,9 @@ router.post('/', validate(createTagSchema), async (req: AuthenticatedRequest, re
       .single();
 
     if (error) {
-      if (error.code === '23505') {
-        return res.status(409).json({ success: false, error: 'A tag with that name already exists' });
+      const appError = parseDbError(error);
+      if (appError) {
+        return res.status(appError.status).json({ success: false, error: appError.message, field: appError.field });
       }
       throw error;
     }
@@ -144,10 +146,16 @@ router.post(
       }
 
       const { error } = await supabase
-        .from('subscription_tag_assignments')
-        .upsert({ subscription_id: subscriptionId, tag_id });
-
-      if (error) throw error;
+        .from('subscription_tags')
+        .insert({ subscription_id: subscriptionId, tag_id });
+
+      if (error) {
+        const appError = parseDbError(error);
+        if (appError) {
+          return res.status(appError.status).json({ success: false, error: appError.message, field: appError.field });
+        }
+        throw error;
+      }
 
       return res.status(200).json({ success: true, data: { assigned: true } });
     } catch (error) {
@@ -180,12 +188,18 @@ router.delete('/subscriptions/:id/tags/:tagId', validate(uuidParamSchema, 'param
     }
 
     const { error } = await supabase
-      .from('subscription_tag_assignments')
+      .from('subscription_tags')
       .delete()
       .eq('subscription_id', subscriptionId)
       .eq('tag_id', tagId);
 
-    if (error) throw error;
+    if (error) {
+      const appError = parseDbError(error);
+      if (appError) {
+        return res.status(appError.status).json({ success: false, error: appError.message, field: appError.field });
+      }
+      throw error;
+    }
 
     return res.status(200).json({ success: true, data: { removed: true } });
   } catch (error) {