authorization.yaml

# Authorization Security Code Review Guidelines
# Comprehensive rules for authorization and access control best practices
# Version: 1.0
# Last Updated: 2026-01-02

name: Authorization Security Guidelines
description: Code review guidelines for authorization security covering access control, resource authorization, API authorization, admin functions, and data access

globs:
  - "**/*.py"
  - "**/*.js"
  - "**/*.ts"
  - "**/*.java"
  - "**/*.go"
  - "**/*.rb"
  - "**/*.php"
  - "**/*.cs"
  - "**/*auth*"
  - "**/*permission*"
  - "**/*role*"
  - "**/*access*"
  - "**/*policy*"
  - "**/*admin*"
  - "**/*controller*"
  - "**/*handler*"

rules:
  # ============================================================================
  # ACCESS CONTROL RULES
  # ============================================================================
  
  - name: implement-rbac-correctly
    description: >
      Implement Role-Based Access Control with well-defined roles and permissions. Avoid
      hardcoded role checks; use permission-based checks instead. Roles should be data-driven
      and configurable. Consider attribute-based access control (ABAC) for complex scenarios.
    severity: high

  - name: enforce-permission-checks
    description: >
      Every endpoint, controller action, and service method that accesses protected resources
      must have explicit permission checks. Use declarative annotations/decorators where
      possible. Never rely solely on UI hiding for access control. Verify on the server side.
    severity: critical

  - name: apply-least-privilege
    description: >
      Grant minimum permissions necessary for each role and user. Default to deny access.
      Regularly audit and revoke unnecessary permissions. Implement just-in-time access
      elevation for sensitive operations rather than persistent elevated privileges.
    severity: high

  - name: centralize-authorization-logic
    description: >
      Centralize authorization logic in a single module/service to ensure consistency.
      Avoid scattered permission checks with different logic. Use a policy engine or
      authorization framework (OPA, Casbin, etc.) for complex scenarios.
    severity: medium

  - name: validate-role-assignments
    description: >
      Validate that role assignments are authorized - users shouldn't be able to assign
      roles they don't have permission to grant. Implement role hierarchy properly.
      Log all role changes with full audit trail.
    severity: high

  # ============================================================================
  # RESOURCE AUTHORIZATION RULES
  # ============================================================================

  - name: validate-resource-ownership
    description: >
      Always verify the authenticated user owns or has permission to access the requested
      resource. Check ownership at the data layer, not just the API layer. Use scoped
      queries that automatically filter by user/tenant context.
    severity: critical

  - name: prevent-horizontal-privilege-escalation
    description: >
      Ensure users cannot access other users' resources by manipulating IDs, parameters,
      or references. Validate resource ownership on every request. Use indirect references
      (UUIDs) rather than sequential IDs to reduce enumeration attacks.
    severity: critical

  - name: prevent-idor-vulnerabilities
    description: >
      Insecure Direct Object References (IDOR) occur when user-supplied input directly
      references objects. Always authorize access based on user context, not just valid
      object existence. Implement resource-level access control checks on all data access.
    severity: critical

  - name: implement-tenant-isolation
    description: >
      In multi-tenant systems, enforce strict tenant isolation at all layers. Use tenant
      context in all queries. Implement row-level security where supported. Regularly
      audit for cross-tenant data access. Consider separate schemas or databases for
      sensitive tenants.
    severity: critical

  - name: validate-resource-relationships
    description: >
      When accessing nested resources, validate the entire relationship chain. Verify that
      parent resources belong to the user before accessing children. Prevent access via
      valid child IDs that belong to unauthorized parents.
    severity: high

  # ============================================================================
  # API AUTHORIZATION RULES
  # ============================================================================

  - name: validate-token-scopes
    description: >
      Validate that OAuth/API token scopes are sufficient for the requested operation.
      Implement fine-grained scopes. Reject requests with missing or insufficient scopes.
      Don't grant broad scopes by default. Document scope requirements for each endpoint.
    severity: high

  - name: secure-api-key-management
    description: >
      API keys should be hashed in storage, have expiration dates, support revocation,
      and be scoped to specific operations/resources. Implement key rotation. Log key
      usage. Detect and alert on anomalous usage patterns.
    severity: high

  - name: implement-service-to-service-auth
    description: >
      Service-to-service communication must be authenticated and authorized. Use mutual
      TLS, JWT with service identities, or API tokens. Validate caller service identity.
      Implement service-level access control policies. Don't trust internal network alone.
    severity: high

  - name: authorize-batch-operations
    description: >
      Batch operations must authorize each individual item, not just the batch request.
      Partial authorization should be handled explicitly (reject all vs process authorized).
      Return clear indication of which items succeeded/failed. Log batch authorization
      decisions.
    severity: high

  # ============================================================================
  # ADMIN FUNCTION RULES
  # ============================================================================

  - name: protect-privileged-operations
    description: >
      Privileged operations require additional verification: re-authentication, MFA,
      approval workflows, or time-limited elevation. Implement break-glass procedures
      for emergencies. All privileged operations should be auditable.
    severity: critical

  - name: implement-audit-logging
    description: >
      Log all authorization decisions, especially denials and privileged access. Include
      user identity, action, resource, timestamp, and outcome. Use tamper-evident logging.
      Retain logs per compliance requirements. Alert on suspicious patterns.
    severity: high

  - name: enforce-separation-of-duties
    description: >
      Critical operations should require multiple approvers or prevent single user from
      completing sensitive workflows. Implement maker-checker patterns for financial
      operations. Prevent privilege accumulation. Regularly review access combinations.
    severity: high

  - name: secure-admin-interfaces
    description: >
      Admin interfaces must have additional protection: separate authentication, IP
      restrictions, VPN requirements, enhanced logging. Consider separate admin domains
      to prevent XSS from user content. Implement session timeout for admin sessions.
    severity: high

  - name: limit-admin-api-exposure
    description: >
      Admin APIs should not be exposed publicly. Use internal networks, API gateways
      with IP restrictions, or separate admin endpoints. Never expose admin functionality
      through the same API as user functionality without proper segregation.
    severity: high

  # ============================================================================
  # DATA ACCESS RULES
  # ============================================================================

  - name: implement-field-level-permissions
    description: >
      Implement field-level access control for sensitive data. Different roles may see
      different fields of the same resource. Mask or redact sensitive fields based on
      permissions. Apply field filtering consistently in all data access paths.
    severity: high

  - name: apply-query-filtering
    description: >
      Apply authorization filters at the query level, not just application level. Use
      database row-level security features where available. Ensure aggregate queries
      don't leak data. Test that filters work with all query variations (sorting, pagination).
    severity: high

  - name: prevent-data-leakage
    description: >
      Prevent data leakage through error messages, metadata, or side channels. Don't
      reveal existence of unauthorized resources. Sanitize exceptions before returning.
      Monitor for unusual data access patterns. Implement data loss prevention controls.
    severity: high

  - name: secure-export-operations
    description: >
      Data export operations must respect authorization. Apply same access controls to
      exported data as real-time access. Consider additional approval for bulk exports.
      Log export operations. Apply watermarking or tracking where appropriate.
    severity: medium

  - name: validate-search-authorization
    description: >
      Search results must be filtered by authorization. Don't index or return unauthorized
      data in search results. Apply consistent authorization across full-text search,
      faceted search, and autocomplete. Test search authorization thoroughly.
    severity: high

  - name: secure-shared-resources
    description: >
      When resources can be shared, validate sharing permissions. Implement share link
      security (expiration, passwords, download limits). Allow resource owners to revoke
      access. Log sharing activities. Consider data classification in sharing policies.
    severity: medium