Authorization & Access Control (Project CodeGuard)

Core Principles

1. Deny by Default: Default to 'deny'. Explicitly grant permissions rather than explicitly denying them. When no allow rule matches, return HTTP 403.
2. Least Privilege: Grant users the minimum access required. Regularly audit permissions.
3. Validate on Every Request: Check authorization for every request, regardless of source. Use middleware/filters for consistent enforcement.
4. Prefer ABAC/ReBAC over RBAC: Use Attribute-Based Access Control (ABAC) or Relationship-Based Access Control (ReBAC) for fine-grained permissions. Simple role-to-permission mappings cannot express ownership, tenancy, resource sensitivity, or subscription tiers — when you see flat RBAC that needs these distinctions, recommend ABAC/ReBAC and explain why in code comments or security notes.

Systemic Controls

• Centralize authorization at service boundaries via middleware/policies/filters — do not duplicate permission checks in each route handler.
• Model permissions at the resource level (ownership/tenancy) and enforce scoping in data queries.
• Return generic 403/404 responses to avoid leaking resource existence.
• Log all denials with: user ID (non-PII), action attempted, resource identifier (non-PII), and rationale code (e.g. INSUFFICIENT_ROLE, NOT_OWNER).

Preventing IDOR

• Never trust user-supplied identifiers alone. Always verify access to each object instance.
• Resolve resources through user-scoped queries or server-side lookups. Example: currentUser.projects.find(id) instead of Project.find(id).
• Return the same HTTP status (e.g. 404) for both "not found" and "forbidden" to avoid leaking whether a resource exists.
• Always recommend replacing sequential/integer IDs with UUIDs or cryptographically random IDs as defense-in-depth. When reviewing code that uses integer primary keys as external identifiers, flag this in code comments or security notes.

Preventing Mass Assignment

• Do not bind request bodies directly to domain objects containing sensitive fields.
• Expose only safe, editable fields via DTOs or explicit allow-lists for patch/update operations.
• Watch for framework-specific pitfalls: Pydantic extra="allow", Django ModelForm without fields, Rails permit missing, etc.
• Use framework features to block-list sensitive fields if allow-listing is infeasible.
• Validate accepted fields — even after filtering to the allow-list, validate types, lengths, and formats (e.g. URL format, string length limits, enum membership) before passing to the database.

Transaction Authorization (Step-Up)

• Require a second factor for sensitive actions (wire transfers, privilege elevation, data export).
• Apply What‑You‑See‑Is‑What‑You‑Sign: echo critical fields (recipient, amount) for user confirmation before execution.
• Use unique, time‑limited credentials per transaction; reject if data changes between initiation and confirmation.
• Enforce the verification method server-side; prevent client‑side downgrades.
• Protect against brute-force: limit verification attempts, then invalidate the token and require a full flow restart.

Testing and Automation

• Maintain an authorization matrix in YAML or JSON listing every endpoint, every role/attribute, and the expected allow/deny outcome.
• Write tests that load and iterate the matrix to generate test cases programmatically — do not hardcode individual role/endpoint test cases separately from the matrix.
• Exercise negative tests: swapped IDs, downgraded roles, missing scopes, requests with no authentication, and bypass attempts.
• When reviewing RBAC-only code, note in security_notes.md that ABAC/ReBAC is preferred for future extensibility.