n8n/cubic.yaml

# yaml-language-server: $schema=https://cubic.dev/schema/cubic-repository-config.schema.json

# cubic.yaml
# This file configures AI review behavior, ignore patterns, PR descriptions, and custom rules.
# Place this file in your repository root to version-control your AI review settings.
# Settings defined here take precedence over UI-configured settings.
# See https://docs.cubic.dev/configure/cubic-yaml for documentation.

version: 1
reviews:
  enabled: true
  sensitivity: medium
  incremental_commits: true
  show_ai_feedback_buttons: false
  custom_instructions: |-
    ## Step 1: Fetch Current Guidelines

    1. Fetch the current [CONTRIBUTING.md](https://github.com/n8n-io/n8n/blob/master/CONTRIBUTING.md) from the repository's main branch
    2. Navigate to the "Community PR Guidelines" section
    3. Use ONLY this live version - ignore any cached/embedded rules

    ## Step 2: Review Process

    Evaluate the PR against the rules in the fetched Community PR Guidelines.

    ## Step 3: Test Requirement Interpretation

    BE REASONABLE when evaluating test coverage:

    **PASS if:**

    - Core functionality has tests
    - Critical paths are tested
    - Coverage is reasonable (not necessarily 100%)

    **DO NOT require tests for:**

    - Exports, types, configs
    - Metadata files
    - Version files

    Approve if reasonably tested. Let humans handle edge cases.

    ## Step 4: Design System Tokens

    For any hard-coded visual values in CSS (colors, shadows, spacing), check
    `@n8n/design-system/src/css/_primitives.scss` and
    `@n8n/design-system/src/css/_tokens.scss` for an appropriate alternative.
    If one exists, suggest using it. If none exist, ask why the hard-coded
    value is required.    
  custom_rules:
    - name: Tests
      description: |-
        BE REASONABLE when evaluating test coverage:

        **PASS if:**

        - Core functionality has tests
        - Critical paths are tested
        - Coverage is reasonable (not necessarily 100%)

        **DO NOT require tests for:**

        - Exports, types, configs
        - Metadata files
        - Version files        
    - name: Security Review
      description: |-
        Proactively review PRs and flag security vulnerabilities specific to n8n's architecture:

        **Code Execution & Sandboxing:**
        - Changes that weaken expression evaluation sandbox protections
        - Modifications to Code node sandboxes (JavaScript/Python) that reduce isolation
        - New access to Node.js builtins or external modules in sandboxed contexts
        - Prototype pollution or constructor access bypasses
        - Weakening of prototype sanitizers or function context validators
        - Changes that expose `process.env` access in Code nodes

        **Credential & Secret Handling:**
        - Credentials being logged or exposed in error messages
        - Hardcoded secrets, API keys, or tokens in code
        - Changes to credential encryption/decryption that weaken security
        - OAuth state/CSRF token handling that bypasses validation
        - Webhook requests that don't sanitize auth cookies
        - External secrets provider integrations with insecure configurations
        - Credential access not respecting scope boundaries (instance/project/user)
        - Data fetched via credentials being exposed to unauthorized user groups

        **Authentication & Session Security:**
        - JWT token handling that weakens validation or expiration
        - Missing or disabled cookie security flags (HttpOnly, Secure, SameSite)
        - Changes that bypass MFA enforcement
        - SSO/SAML/OIDC authentication flows with validation gaps
        - OAuth 2.0 implementations missing PKCE or with weak redirect URI validation

        **Authorization & Access Control:**
        - Missing or bypassed RBAC and scope-based permission checks
        - Missing credential permission validation before workflow execution
        - Subworkflow execution that bypasses caller policies or ownership validation
        - Missing project-level or resource-level access controls

        **License Enforcement:**
        - Changes that weaken license enforcement
        - Missing `FeatureNotLicensedError` for unlicensed feature access
        - Bypassed license quota checks
        - New licensed features without proper middleware or module-level enforcement
        - New controller endpoints in `*.ee.ts` files that access licensed features without `@Licensed` decorator
        - `@Licensed` decorator usage that doesn't match feature requirements (check `LICENSE_FEATURES` in `@n8n/constants`)
        - Endpoints in `*.ee.ts` files with `@GlobalScope` or `@ProjectScope` but missing `@Licensed` (license check is separate from permission check)
        - Preferred pattern: `@Licensed` decorator over custom licensing middleware
        - Decorator order should be: route decorator → `@Licensed` → scope decorators
        - Enterprise features not properly isolated in modules (newer features should use the module system)
        - Enterprise code accessible outside of `*.ee.ts` files or licensed modules        
    - name: Use DTOs for Request Body Validation
      description: |-
        - Rule Statement:
        Controller endpoints that accept request bodies must use the `@Body` decorator with a DTO class for runtime validation. TypeScript types alone provide no runtime validation - only `@Body` with a Zod-based DTO (extending `Z.class`) validates incoming data.

        - Detection Criteria:
        Only flag in `*.controller.ts` files when there is positive evidence the developer intended to accept a body but didn't use the pattern:

          1. Parameter named `payload`, `body`, or `data` without `@Body` decorator
          2. Direct `req.body` access in a controller method
          3. `@Body` decorator with a type not ending in `Dto` (indicates unawareness of the DTO pattern)

        Do NOT flag:
          - `@Body` with a type ending in `Dto` (developer knows the pattern)
          - POST/PUT/PATCH endpoints without body parameters (may legitimately have no body)
          - Webhook controllers
          - Existing unchanged code

        - Example Violation:
          ```typescript
          @Post('/')
          async create(req: AuthenticatedRequest, payload: CreateUser) {
            // payload is undefined - missing @Body decorator
          }

          @Post('/')
          async create(req: AuthenticatedRequest) {
            const data = req.body; // No runtime validation
          }

          @Post('/')
          async create(@Body payload: CreateUser) {
            // Type doesn't end in Dto - likely missing Zod validation
          }
          ```

        - Example Allowed:
          ```typescript
          @Post('/')
          async create(@Body payload: CreateUserDto) { ... }

          @Post('/activate')
          async activate(req: AuthenticatedRequest) {
            // Legitimately no body needed
          }
          ```

        - Recommendation:
        Use `@Body` decorator with a DTO class from `@n8n/api-types` or a local `dto/` directory. DTOs must extend `Z.class` from `zod-class` for runtime validation.

        **Input Validation & Injection Prevention:**
        - Unsanitized user input flowing to file paths
        - SQL nodes with expressions in query fields without parameterization
        - Command execution nodes with unsanitized shell arguments
        - Path traversal risks in file operation nodes
        - Community package names with suspicious patterns

        **File System Access:**
        - Changes that weaken file access restriction enforcement
        - File operations that bypass allowlist/blocklist patterns
        - Access to n8n internal directories

        **Database Security & Performance:**
        - Missing indexes on frequently queried columns in migrations
        - Resource-intensive queries without pagination or limits
        - Missing encryption for sensitive fields beyond credentials
        - Raw SQL queries that bypass TypeORM protections

        **HTTP, Webhooks & Network Security:**
        - SSRF risks in user-controlled URLs
        - CORS configuration that allows all origins
        - CSP or iframe sandbox modifications that weaken protections
        - Rate limiting configuration changes that reduce protection
        - Disabled TLS certificate validation (`rejectUnauthorized: false`)

        **Audit Logging & Event Bus:**
        - Missing logging for security-relevant events
        - Sensitive data appearing in logs or error messages
        - Incomplete audit trails for authentication and authorization events

        **Context-aware review:**
        - Higher scrutiny for: expression engine, credential handling, code execution nodes, license enforcement, SSO integrations
        - Consider n8n's security audit categories: credentials, database, nodes, instance, filesystem risks
        - Community/custom nodes have higher risk profile than official nodes        
    - name: Design System Tokens
      description: |-
        For any hard-coded visual values in CSS (colors, shadows, spacing),
        check `@n8n/design-system/src/css/_primitives.scss` and
        `@n8n/design-system/src/css/_tokens.scss` for an appropriate alternative.
        If one exists, suggest using it. If none exist, ask why the hard-coded
        value is required.        
    - name: Use workflowDocumentStore for Migrated Workflow Fields
      description: |-
        We are actively migrating workflow state from `workflowsStore` (Pinia store defined in
        `packages/frontend/editor-ui/src/app/stores/workflows.store.ts`) to `workflowDocumentStore`
        (defined in `packages/frontend/editor-ui/src/app/stores/workflowDocument.store.ts`).

        The `workflowDocumentStore` is the single source of truth for migrated fields.
        When new frontend code reads or writes any of the fields listed below, it **must** use
        `workflowDocumentStore` instead of `workflowsStore.workflow.*` or equivalent accessors.

        **Already-migrated fields (do NOT access via workflowsStore):**
        - `active`
        - `activeVersion`
        - `activeVersionId`
        - `checksum`
        - `createdAt`
        - `homeProject`
        - `meta`
        - `pinData`
        - `settings`
        - `tags`
        - `updatedAt`

        **Detection criteria — flag when NEW code in `packages/frontend/` does any of:**
        1. Reads a migrated field from `workflowsStore.workflow.<field>` (e.g. `workflowsStore.workflow.tags`)
        2. Reads a migrated field from a destructured `workflow` ref originating from `workflowsStore`
        3. Writes to a migrated field through `workflowsStore` (e.g. `workflowsStore.workflow.active = true`)
        4. Calls a `workflowsStore` setter/action that only mutates a migrated field when
           `workflowDocumentStore` already exposes an equivalent method

        **Do NOT flag:**
        - Existing unchanged code (only review new or modified lines)
        - Access to non-migrated fields (e.g. `workflowsStore.workflow.nodes`, `workflowsStore.workflow.connections`)
        - Backend code — this rule applies only to `packages/frontend/`
        - Code inside `workflowDocument.store.ts` or its sub-modules (those *are* the source of truth)
        - Code inside `workflows.store.ts` itself (the migration is still in progress there)

        **Recommendation:**
        Use `useWorkflowDocumentStore(createWorkflowDocumentId(workflowId))` from
        `@/app/stores/workflowDocument.store.ts` to access migrated fields.

        This is an active migration. The list of migrated fields will grow over time.        
pr_descriptions:
  generate: false
  instructions: Each PR is supposed to have a limited scope. In your review, focus on changes made in the PR and avoid pointing out problems you found in the code that already existed.
issues:
  fix_with_cubic_buttons: true