RBAC and Authorization

Enterprise reference for the current CodeGraph authentication, authorization, and machine-access runtime.

Scope and Source of Truth¶

This document describes the implementation currently present under src/.

Canonical code surfaces:

Compatibility imports are intentionally preserved by src/api/auth/__init__.py, which extends the package path with machine, providers, and tokens. New references should prefer the physical module paths above.

Runtime Model¶

CodeGraph uses three related authorization layers:

Authentication methods produce either a user identity or a machine principal. Authorization then checks role permissions, raw scopes, interface allowlists, tenant/project restrictions, and middleware-specific security controls.

User Roles and Permissions¶

Roles¶

User roles are defined twice for separate boundaries:

Both currently use the same values:

src/api/dependencies.py::require_role() treats this as an ordered hierarchy: viewer < analyst < reviewer < admin.

Permission Behavior¶

Permission currently contains 31 values, including admin:all.

Important runtime details:

• ROLE_PERMISSIONS[Role.ADMIN] stores only {Permission.ADMIN_ALL}.
• get_role_permissions(Role.ADMIN) returns that raw set; it does not expand to every permission.
• has_permission(Role.ADMIN, ...) returns True for every requested permission.
• Explicit scopes also grant permissions when the scope string matches the required Permission.value.
• The admin:all scope grants all permission checks in has_permission() and bypasses machine scope checks.

Permission Catalog¶

ROLE_PERMISSIONS does not currently include USERS_*, API_KEYS_DELETE, METRICS_READ, the admin-only digital-employee permissions, or ADMIN_ALL for non-admin roles. They are effectively admin-only through Role.ADMIN or an explicit admin:all scope.

Permission Helpers¶

Use src.api.auth.permissions for role/scope checks:

from src.api.auth.permissions import (
    Permission,
    Role,
    get_default_scopes_for_api_key,
    get_role_permissions,
    has_all_permissions,
    has_any_permission,
    has_permission,
    validate_scopes,
)

Key behavior:

• get_default_scopes_for_api_key() returns scenarios:read, scenarios:execute, query:execute, sessions:read, sessions:write, history:read.
• validate_scopes() filters unknown strings against the Permission enum.
• has_permission() considers role grants first and explicit scope strings second.

FastAPI Auth Context¶

AuthContext is defined in src/api/auth/providers/middleware.py.

Fields:

The main dependency flow is:

1. Reuse request.state.machine_principal if ScopeEnforcementMiddleware has already validated an API key.
2. Check X-YC-IAM-Token if IAM is enabled.
3. Check JWT bearer token and reject blacklisted JWT ids.
4. Check X-API-Key as a machine credential.
5. Return unauthenticated context when no valid credentials exist.

Use these dependencies for route code:

from src.api.auth.middleware import (
    get_auth_context,
    get_current_user,
    get_optional_user,
    require_admin,
    require_analyst,
    require_any_permission,
    require_auth,
    require_auth_or_localhost,
    require_permission,
    require_reviewer,
    require_role,
)

require_auth_or_localhost() allows local plugin traffic only when security.local_dev_unauthenticated_surfaces_enabled is true and the request is loopback. Mutating local-plugin requests must include X-Actor-Agent-Id and X-Task-Id, and generic agent ids such as codex or codex-headless are rejected.

src/api/dependencies.py also contains database-backed dependencies returning ORM User records. Auth-suite routes use those dependencies for account administration and API-key CRUD.

Authentication Methods¶

Local Username and Password¶

Routes are mounted under /api/v1/auth:

Local passwords are hashed with bcrypt. New self-registered users receive the analyst role.

JWT Bearer Tokens¶

JWT code lives in src/api/auth/tokens/jwt_handler.py.

TokenPayload fields:

Defaults:

• Access token TTL: 30 minutes when expires_delta is omitted.
• Refresh token TTL: 7 days.
• Signing settings come from src/api/config.py (API_JWT_ALGORITHM, JWT secret resolution).

Revocation:

• blacklist_token() stores a SHA-256 fingerprint of the JTI in memory and in the token_blacklist table.
• is_token_blacklisted() checks memory first, then the database.
• load_blacklist_cache() loads non-expired blacklist rows at startup.
• _blacklist_sync_task() refreshes the in-memory cache periodically.

User API Keys¶

User API keys are created through /api/v1/me/api-keys and transported as X-API-Key.

Format:

rag_<8 hex chars>_<48 hex chars>

Implementation details:

• generate_api_key() returns (full_key, prefix, key_hash).
• The prefix starts with rag_.
• The secret is secrets.token_hex(24).
• The stored hash is SHA-256.
• verify_api_key() uses secrets.compare_digest().
• ApiKey.group_id optionally limits a key to one tenant group.
• User API keys authenticate as MachinePrincipal(subject_type="user", auth_method="api_key").
• User API keys allow api and mcp interfaces by default.
• ApiKeyInfo is the secret-free response model.
• ApiKeyWithSecret extends ApiKeyInfo and is returned only when the key is created.

API-key CRUD:

The create request defaults to ["scenarios:read", "query:execute"]; the lower-level helper get_default_scopes_for_api_key() returns a broader legacy default list. Route behavior is the authoritative runtime behavior.

Service Accounts¶

Service accounts use the same X-API-Key transport with a distinct credential prefix:

svc_<8 hex chars>_<48 hex chars>

Service-account records are persisted in service_accounts; credentials are persisted in service_account_credentials.

Implemented controls:

• Admin-only service-account management.
• Policy templates: ci, portal, bot, agent.
• Explicit scopes and allowed_interfaces.
• Optional group_id or project_id restriction.
• Account expiry and credential expiry.
• Credential rotation without immediate old-credential revocation.
• Active credential quota through security.service_account_max_active_credentials.
• Revoke and deactivate flows.
• Machine contract header: X-CodeGraph-Machine-Contract, currently 2026-03-v1.
• Optional proxy-terminated mTLS binding for configured interfaces.
• Unified machine audit events through AuditAction.MACHINE_ACCESS.

Admin routes:

Policy templates:

OAuth2/OIDC¶

OAuth code lives in src/api/auth/providers/oauth.py; routes live in auth_external_routes.py.

Supported provider implementations:

Routes:

Configured OAuth users receive JWTs using their persisted database role.

LDAP/Active Directory¶

LDAP code lives in src/api/auth/providers/ldap_auth.py; route integration exists in auth_external_routes.py.

Routes:

Runtime caveat: LDAPAuthenticator.map_groups_to_role() reads config.group_role_mapping. Ensure the deployed LDAPConfig provides that attribute or all LDAP-created users fall back to analyst.

Yandex Cloud IAM¶

IAM validation lives in src/api/auth/providers/iam.py and is initialized from API settings when IAM is enabled.

Request header:

X-YC-IAM-Token: <token>

When the token validates, get_auth_context() returns:

• role=Role.ANALYST
• scopes=["scenarios:read", "query:execute", "review:execute"]
• auth_method="iam"

Validation results are cached for the configured IAM token cache TTL.

Machine Scope Enforcement¶

ScopeEnforcementMiddleware is added in src/api/main.py when security.api_key_scope_enforcement is true. It checks requests with X-API-Key before the router executes.

Process:

1. Validate the key as a user API key or service-account credential.
2. Save MachinePrincipal on request.state.machine_principal.
3. Resolve requested project scope from X-Project-Id.
4. Validate optional machine contract header.
5. Validate optional mTLS binding for service accounts.
6. Run authorize_machine_request().
7. Emit a machine audit event.
8. Return 403 insufficient_scope on denial.

API route scope map excerpt:

MCP route scope map:

For MCP only, mcp:access can be satisfied by aliases including query:execute, scenarios:read, scenarios:execute, review:execute, stats:read, history:read, and admin:all.

Explicit endpoint scope checks can use:

from src.api.auth.tokens.scope_enforcement import require_scope

@router.get("/example")
async def example(auth=Depends(require_scope("query:execute"))):
    ...

require_scope() checks raw AuthContext.scopes; admin:all bypasses it.

Tenant and Project Access¶

Tenant/project authorization is modeled separately from global user roles.

Enums and tables:

Admin access-management routes:

Guardrails:

• A platform admin cannot deactivate their own account.
• The last active platform admin cannot be deactivated or downgraded.
• The last tenant admin cannot be removed or downgraded without another tenant admin.
• selected project scope must include at least one project, and all selected projects must belong to the assigned tenant.
• all project scope cannot include explicit project ids.

Project resolution and tenant-sensitive runtime paths must use ProjectContext and resolved project scope, not user-provided database paths.

Path Validation Middleware¶

PathValidationMiddleware validates db_path and source_path fields in JSON bodies for POST, PUT, and PATCH requests.

Rules:

• Empty strings and NUL bytes are rejected.
• Relative paths are rejected when path_validation_deny_relative is true.
• .. path components are rejected.
• Paths are resolved with os.path.realpath().
• The resolved path must be under an allowed base directory.

Allowed directories are built from:

• security.path_validation_allowed_base_dirs
• registered project db_path parent directories
• registered project source_path directories

Config fields are defined in SecurityConfig:

Webhook Authentication¶

Webhook verification lives in src/api/auth/machine/webhook_auth.py. The main verification function is verify_webhook_signature().

Supported platforms:

sourcecraft, gitverse, and github use HMAC signature validation. gitlab uses constant-time token comparison. Replay protection uses the configured security.webhook_max_age_seconds default when a platform timestamp header exists.

Audit and SIEM-Relevant Events¶

Audit actions are defined in src/api/logging/audit_logger.py.

Relevant authorization actions include:

Machine audit records include subject type/id, interface, operation, resource, result, credential id, optional service-account id, optional contract version, project id, and group id.

Configuration Reference¶

Selected current config fields:

Operational Guidance¶

For administrators:

1. Use admin only for platform administration.
2. Prefer tenant GroupRole and selected project access for day-to-day segregation.
3. Use service accounts for CI, bots, portals, MCP clients, and long-lived machine access.
4. Use policy templates as a baseline and add only the scopes needed by the caller.
5. Rotate service-account credentials before revoking old credentials.
6. Keep JWT blacklist cache loading enabled during application startup.
7. Keep path validation and API-key scope enforcement enabled in shared environments.

For developers:

1. Use require_permission() or require_role() for human user route checks.
2. Use require_scope() only when raw scope strings are the intended contract.
3. Add new machine routes to API_ROUTE_SCOPE_MAP or MCP_ROUTE_SCOPE_MAP.
4. Preserve REST/MCP parity by calling shared services rather than duplicating auth logic.
5. Never authorize tenant-sensitive operations from user-provided db_path.
6. For local-plugin mutating routes, require named actor and task evidence.
7. Do not log bearer tokens, API keys, service-account secrets, raw webhook secrets, or raw prompts.

Related Documents¶

• Enterprise Security Brief
• OAuth2/OIDC and LDAP/AD Integration
• SIEM Integration
• DLP Security
• REST API Reference

Version: 3.0 | May 2026