Merge pull request #2 from base/feat-priv-670-add-trait-validator

feat(PRIV-670): add trait validator

Author: patnir

docs/api.md

@@ -24,6 +24,8 @@ Check if a wallet has a specific verification and retrieve the verification toke
 
 **Important:** This endpoint must only be called from your backend. Never expose your secret key in frontend code.
 
+**Security Requirement:** Before calling this endpoint, your backend **MUST** validate that the trait requirements in the SIWE message match what your backend expects. See [Security Best Practices](/docs/security#validate-trait-requirements) for details.
+
 ### Request
 
 ```ts
@@ -33,6 +35,33 @@ Check if a wallet has a specific verification and retrieve the verification toke
 }
 ```
 
+### Backend Validation Required
+
+Before forwarding the request to Base Verify, validate trait requirements:
+
+```typescript
+import { validateTraits } from './lib/trait-validator';
+
+// Define expected traits (must match frontend)
+const expectedTraits = {
+  'verified': 'true',
+  'followers': 'gte:1000'
+};
+
+// Validate message contains expected traits
+const validation = validateTraits(message, 'x', expectedTraits);
+
+if (!validation.valid) {
+  return res.status(400).json({
+    error: 'Invalid trait requirements in message'
+  });
+}
+
+// Safe to forward to Base Verify API
+```
+
+This prevents users from modifying trait requirements on the frontend to bypass your access controls.
+
 ### Example Request
 
 ```bash

docs/security.md

@@ -82,6 +82,48 @@ Users can delete their verifications at any time:
 
 ## Best Practices
 
+### Validate Trait Requirements
+
+**Critical Security Requirement:**
+
+When your backend receives a SIWE message from the frontend, you **MUST** validate that the trait requirements in the message match what your backend expects. This prevents users from modifying trait requirements on the frontend to bypass your access controls.
+
+**Example Attack Without Validation:**
+1. Your app requires users to have 100 followers
+2. User modifies the frontend to request only 10 followers
+3. User signs the modified message
+4. Without validation, your backend forwards the request to Base Verify
+5. User gains access with less than 100 followers ❌
+
+**Implementation:**
+
+```typescript
+import { validateTraits } from './lib/trait-validator';
+
+// Define what traits your app requires
+const expectedTraits = {
+  'followers': 'gte:100'
+};
+
+// Validate before forwarding to Base Verify
+const validation = validateTraits(message, 'x', expectedTraits);
+
+if (!validation.valid) {
+  return res.status(400).json({
+    error: 'Invalid trait requirements in message',
+    details: validation.error
+  });
+}
+
+// Now safe to forward to Base Verify API
+```
+
+**Key Points:**
+- Trait requirements in SIWE message are embedded as URNs (e.g., `urn:verify:provider:x:followers:gte:100`)
+- Users can modify these before signing
+- Backend must validate they match expected requirements
+- Validation must happen **before** calling Base Verify API
+
 ### Protect Your Secret Key
 
 **Never:**

lib/trait-validator.ts

@@ -0,0 +1,194 @@
+/**
+ * Trait Validation Utility
+ * 
+ * Validates that SIWE message trait requirements match backend expectations.
+ * This prevents users from modifying trait requirements on the frontend.
+ */
+
+export interface TraitRequirement {
+  [traitName: string]: string; // e.g., { 'verified': 'true', 'followers': 'gte:1000' }
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  error?: string;
+  provider?: string;
+  foundTraits?: TraitRequirement;
+  expectedTraits?: TraitRequirement;
+}
+
+/**
+ * Parse trait URNs from SIWE message resources
+ * Format: urn:verify:provider:{provider}:{trait_name}:{operation}:{value}
+ * 
+ * @param message - The SIWE message string
+ * @returns Object with provider and traits, or null if no provider found
+ */
+function parseTraitsFromMessage(message: string): { provider: string; traits: TraitRequirement } | null {
+  // Extract resources section from SIWE message
+  const resourcesMatch = message.match(/Resources:\s*\n((?:- .+\n)+)/);
+  if (!resourcesMatch) {
+    return null;
+  }
+
+  const resources = resourcesMatch[1]
+    .split('\n')
+    .map(line => line.replace(/^- /, '').trim())
+    .filter(line => line.length > 0);
+
+  // Find provider URN
+  const providerUrn = resources.find(r => r.match(/^urn:verify:provider:[^:]+$/));
+  if (!providerUrn) {
+    return null;
+  }
+
+  const providerMatch = providerUrn.match(/^urn:verify:provider:([^:]+)$/);
+  if (!providerMatch) {
+    return null;
+  }
+
+  const provider = providerMatch[1];
+  const traits: TraitRequirement = {};
+
+  // Parse trait URNs for this provider
+  const traitPattern = new RegExp(`^urn:verify:provider:${provider}:([^:]+):([^:]+):(.+)$`);
+  
+  resources.forEach(resource => {
+    const traitMatch = resource.match(traitPattern);
+    if (traitMatch) {
+      const [, traitName, operation, value] = traitMatch;
+      
+      // Reconstruct the trait value with operation prefix
+      // (except for 'eq' which is the default and can be omitted)
+      if (operation === 'eq') {
+        traits[traitName] = value;
+      } else {
+        traits[traitName] = `${operation}:${value}`;
+      }
+    }
+  });
+
+  return { provider, traits };
+}
+
+/**
+ * Normalize trait requirement for comparison
+ * Handles the 'eq' operation being implicit
+ * 
+ * @param value - The trait value (e.g., 'true', 'gte:1000')
+ * @returns Normalized value with explicit operation
+ */
+function normalizeTraitValue(value: string): string {
+  // If value doesn't have an operation prefix, it's implicitly 'eq'
+  if (!value.match(/^(eq|gt|gte|lt|lte|in):/)) {
+    return `eq:${value}`;
+  }
+  return value;
+}
+
+/**
+ * Validate that message traits match expected requirements
+ * 
+ * @param message - The SIWE message string
+ * @param expectedProvider - Expected provider name (e.g., 'x', 'coinbase')
+ * @param expectedTraits - Expected trait requirements
+ * @returns ValidationResult with validation status and details
+ */
+export function validateTraits(
+  message: string,
+  expectedProvider: string,
+  expectedTraits: TraitRequirement
+): ValidationResult {
+  // Parse traits from message
+  const parsed = parseTraitsFromMessage(message);
+  
+  if (!parsed) {
+    return {
+      valid: false,
+      error: `No provider found in SIWE message`,
+      expectedTraits
+    };
+  }
+
+  const { provider, traits: foundTraits } = parsed;
+
+  // Check provider matches
+  if (provider !== expectedProvider) {
+    return {
+      valid: false,
+      error: `Provider mismatch: expected '${expectedProvider}', found '${provider}'`,
+      provider,
+      foundTraits,
+      expectedTraits
+    };
+  }
+
+  // Normalize all trait values for comparison
+  const normalizedExpected: Record<string, string> = {};
+  Object.entries(expectedTraits).forEach(([key, value]) => {
+    normalizedExpected[key] = normalizeTraitValue(value);
+  });
+
+  const normalizedFound: Record<string, string> = {};
+  Object.entries(foundTraits).forEach(([key, value]) => {
+    normalizedFound[key] = normalizeTraitValue(value);
+  });
+
+  // Check all expected traits are present with correct values
+  const missingTraits: string[] = [];
+  const mismatchedTraits: Array<{ trait: string; expected: string; found: string }> = [];
+
+  Object.entries(normalizedExpected).forEach(([traitName, expectedValue]) => {
+    if (!(traitName in normalizedFound)) {
+      missingTraits.push(traitName);
+    } else if (normalizedFound[traitName] !== expectedValue) {
+      mismatchedTraits.push({
+        trait: traitName,
+        expected: expectedValue,
+        found: normalizedFound[traitName]
+      });
+    }
+  });
+
+  // Check for unexpected traits (traits in message but not in expected)
+  const unexpectedTraits = Object.keys(normalizedFound).filter(
+    key => !(key in normalizedExpected)
+  );
+
+  // Build error message if validation fails
+  if (missingTraits.length > 0 || mismatchedTraits.length > 0 || unexpectedTraits.length > 0) {
+    const errors: string[] = [];
+    
+    if (missingTraits.length > 0) {
+      errors.push(`Missing required traits: ${missingTraits.join(', ')}`);
+    }
+    
+    if (mismatchedTraits.length > 0) {
+      const details = mismatchedTraits
+        .map(({ trait, expected, found }) => `${trait} (expected: ${expected}, found: ${found})`)
+        .join('; ');
+      errors.push(`Trait value mismatch: ${details}`);
+    }
+    
+    if (unexpectedTraits.length > 0) {
+      errors.push(`Unexpected traits: ${unexpectedTraits.join(', ')}`);
+    }
+
+    return {
+      valid: false,
+      error: errors.join('. '),
+      provider,
+      foundTraits,
+      expectedTraits
+    };
+  }
+
+  // All checks passed
+  return {
+    valid: true,
+    provider,
+    foundTraits,
+    expectedTraits
+  };
+}
+

package.json

@@ -43,5 +43,6 @@
     "eslint-config-next": "15.0.3",
     "prisma": "^5.20.0",
     "typescript": "^5.4.5"
-  }
+  },
+  "packageManager": "yarn@1.22.22+sha512.a6b2f7906b721bba3d67d4aff083df04dad64c399707841b7acf00f6b133b7ac24255f2652fa22ae3534329dc6180534e98d17432037ff6fd140556e2bb3137e"
 }

pages/api/coinbase/verify-token.ts

@@ -1,6 +1,7 @@
 import { NextApiRequest, NextApiResponse } from 'next';
 import { config } from '../../../lib/config';
 import prisma from '../../../lib/prisma';
+import { validateTraits } from '../../../lib/trait-validator';
 
 export default async function handler(req: NextApiRequest, res: NextApiResponse) {
   if (req.method !== 'POST') {
@@ -17,6 +18,27 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse)
       });
     }
 
+    // Define expected trait requirements for Coinbase verification
+    // This MUST match what the frontend generates
+    const expectedTraits = {
+      'coinbase_one_active': 'true',
+      'country': 'in:US,CA,MX'
+    };
+
+    // Validate that the message contains the expected trait requirements
+    const validation = validateTraits(message, 'coinbase', expectedTraits);
+    
+    if (!validation.valid) {
+      console.error('Trait validation failed:', validation.error);
+      console.error('Expected traits:', validation.expectedTraits);
+      console.error('Found traits:', validation.foundTraits);
+      
+      return res.status(400).json({
+        error: 'Invalid trait requirements in message',
+        details: validation.error
+      });
+    }
+
     const requestBody: any = {
       signature,
       message

pages/api/verify-token.ts

@@ -1,6 +1,7 @@
 import { NextApiRequest, NextApiResponse } from 'next';
 import { config } from '../../lib/config';
 import prisma from '../../lib/prisma';
+import { validateTraits } from '../../lib/trait-validator';
 
 export default async function handler(req: NextApiRequest, res: NextApiResponse) {
   if (req.method !== 'POST') {
@@ -17,6 +18,26 @@ export default async function handler(req: NextApiRequest, res: NextApiResponse)
       });
     }
 
+    // Define expected trait requirements for X verification
+    // This MUST match what the frontend generates
+    const expectedTraits = {
+      'verified': 'true'
+    };
+
+    // Validate that the message contains the expected trait requirements
+    const validation = validateTraits(message, 'x', expectedTraits);
+    
+    if (!validation.valid) {
+      console.error('Trait validation failed:', validation.error);
+      console.error('Expected traits:', validation.expectedTraits);
+      console.error('Found traits:', validation.foundTraits);
+      
+      return res.status(400).json({
+        error: 'Invalid trait requirements in message',
+        details: validation.error
+      });
+    }
+
     const requestBody: any = {
       signature,
       message