Design Patterns & Decisions

// Code manifests registered at import time
registerCodeManifest(awsManifest);
registerCodeManifest(githubManifest);
// ...9 total code-based integrations
 
// Dynamic manifests from database at runtime
registerDynamicManifest(dbManifest);
 
// Lookup
getManifest('aws');  // Returns full manifest with checks, auth, etc.

// Auth strategy varies per integration:
auth: 
  | { type: 'oauth2', clientId, clientSecret, scopes, ... }
  | { type: 'api_key', headerName, prefix, ... }
  | { type: 'basic', ... }
  | { type: 'jwt', ... }
  | { type: 'custom', ... }

// Each adapter implements:
interface CloudSecurityAdapter {
  scan(credentials, options): Promise<Finding[]>;
}
 
// Adapters for: S3, RDS, EC2, Lambda, IAM, CloudTrail, 
// SecurityHub, GuardDuty, ECS, EKS, etc.

// JSON definition → executable check
{
  steps: [
    { type: 'fetch', path: '/api/repos', as: 'repos' },
    { type: 'forEach', items: '$.repos', as: 'repo',
      steps: [
        { type: 'fetch', path: '/api/repos/{{repo.id}}/settings' },
        { type: 'branch', condition: { field: 'branchProtection', op: 'falsy' },
          then: [{ type: 'emit', result: 'fail', ... }],
          else: [{ type: 'emit', result: 'pass', ... }]
        }
      ]
    }
  ]
}

@Controller({ path: 'controls', version: '1' })
@UseGuards(HybridAuthGuard, PermissionGuard)  // Auth + RBAC
@UseInterceptors(AuditLogInterceptor)          // Automatic audit logging
export class ControlsController {
  
  @Post()
  @RequirePermission('control', 'create')      // Endpoint-level permission
  @SkipAuditLog()                              // Opt out of audit
  create() { ... }
}

// Every check gets a rich context with pre-built helpers:
check.run(async (ctx) => {
  // HTTP methods auto-inject auth headers
  const repos = await ctx.fetchAllPages('/api/repos');
  
  for (const repo of repos) {
    if (repo.branchProtection) {
      ctx.pass({ title: `${repo.name} has branch protection`, ... });
    } else {
      ctx.fail({ title: `${repo.name} missing branch protection`, ... });
    }
  }
});

// Optimistic update with rollback
const updateTask = async (taskId, data) => {
  await mutate(
    cacheKey,
    async (current) => {
      const result = await apiClient.patch(`/tasks/${taskId}`, data);
      return { ...current, data: current.data.map(t => 
        t.id === taskId ? result.data : t
      )};
    },
    { optimisticData: (current) => ({
      ...current,
      data: current.data.map(t => 
        t.id === taskId ? { ...t, ...data } : t
      )
    })}
  );
};

// Factory creates the right handler based on integration type
const handler = createHandler(integration.integrationId);
// Returns: provider-specific check runner with correct auth

// Server component (page.tsx)
export default async function ControlsPage({ params }) {
  const { data } = await serverApi.get('/v1/controls');
  return <ControlsClient initialData={data} />;
}
 
// Client component
function ControlsClient({ initialData }) {
  const { data } = useSWR('/v1/controls', fetcher, {
    fallbackData: initialData,
    revalidateOnMount: !initialData,
  });
  // Renders with SSR data immediately, then revalidates
}

const [sheetOpen, setSheetOpen] = useQueryState('risk-sheet');
// URL: /vendors/vnd_123?risk-sheet=true
// Benefits: shareable links, back button works, survives refresh

const isDesktop = useMediaQuery('(min-width: 768px)');
 
return isDesktop ? (
  <Sheet open={isOpen}>
    <SheetContent><SheetHeader>...</SheetHeader><SheetBody>...</SheetBody></SheetContent>
  </Sheet>
) : (
  <Drawer open={isOpen}>
    <DrawerContent>...</DrawerContent>
  </Drawer>
);

// 1. Define schema
const schema = z.object({
  name: z.string().min(1),
  website: z.string().url().optional().or(z.literal('')),
  category: z.nativeEnum(VendorCategory),
});
 
// 2. Infer type
type FormData = z.infer<typeof schema>;
 
// 3. Use form
const form = useForm<FormData>({
  resolver: zodResolver(schema),
  mode: 'onChange',
});
 
// 4. Controller for complex inputs
<Controller
  name="category"
  control={form.control}
  render={({ field }) => <Select {...field} />}
/>

// Controller: HTTP concerns only
@Post()
@RequirePermission('control', 'create')
async create(
  @OrganizationId() orgId: string,
  @Body() dto: CreateControlDto,
) {
  return this.controlsService.create(orgId, dto);
}
 
// Service: Business logic
async create(orgId: string, dto: CreateControlDto) {
  return this.db.control.create({
    data: { ...dto, organizationId: orgId },
  });
}

// Every service method takes organizationId as first parameter
// Every Prisma query includes WHERE organizationId = ?
// Never trust client-supplied orgId for data access
 
async findOne(orgId: string, id: string) {
  return this.db.control.findFirst({
    where: { id, organizationId: orgId },  // Both conditions
  });
}

// AuditLogInterceptor (global, automatic)
// 1. Before handler: fetch previous state for PATCH/PUT
// 2. After handler: compute diff
// 3. Store: { changes: { field: { previous, current } } }
 
// ONLY fires when:
// - HTTP method is POST/PATCH/PUT/DELETE (or @AuditRead() on GET)
// - @RequirePermission metadata is present
// - @SkipAuditLog() is NOT present

member.role = "admin,auditor"  // String field

// Service tokens are simple env vars
X-Service-Token: ${SERVICE_TOKEN_TRIGGER}

// Key format: comp_ + 32 hex chars
// Prefix: first 8 chars after comp_
// Lookup: SELECT * FROM api_key WHERE keyPrefix = 'abc12345'
// Then: SHA256 compare against full key hash
 
// O(1) lookup without storing the plaintext key
// Legacy fallback: scan all keys if prefix not yet backfilled

// Check author writes:
const data = await ctx.get('/api/repos');
 
// CheckContext transparently:
// 1. Looks up auth strategy (OAuth? API key? Bearer?)
// 2. Refreshes token if expired
// 3. Injects correct header (Authorization: Bearer ..., X-API-Key: ..., etc.)
// 4. Handles pagination if needed

check: {
  taskMapping: TASK_TEMPLATES.codeChanges,
  run: async (ctx) => {
    ctx.pass({ ... });  // This auto-completes linked tasks
  }
}

// PostgreSQL advisory locks prevent concurrent AI assessment of the same vendor
// Keyed by website domain hash
// Prevents: duplicate Firecrawl calls, race conditions on save
await db.$executeRaw`SELECT pg_advisory_lock(${hash})`;

// main.ts: ValidationPipe with transform: true
// This mangles nested JSON objects (like TipTap content)
// Workaround: Use @Req() req for complex payloads
// This is documented but easily forgotten