authz v1 project level

[omar-inkeep]

No description provided.

[changeset-bot]

⚠️ No Changeset found

Latest commit: f2ec7b5

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Review	Updated (UTC)
agents-docs	Ready	Preview, Comment	Jan 19, 2026 4:08pm
agents-eval-api	Ready	Preview, Comment	Jan 19, 2026 4:08pm
agents-manage-api	Ready	Preview, Comment	Jan 19, 2026 4:08pm
agents-manage-ui	Ready	Preview, Comment	Jan 19, 2026 4:08pm
agents-run-api	Ready	Preview, Comment	Jan 19, 2026 4:08pm

[claude]

Claude finished @omar-inkeep's task —— View job

---

Code Review: Authorization V1 Project Level Implementation

This is a comprehensive implementation of project-level authorization using SpiceDB. I've conducted a thorough review across the architecture, security, performance, and user experience dimensions.

Todo List:

• Read repository guidelines and setup instructions
• Understand the authorization model and SpiceDB schema
• Review core authorization logic and middleware
• Analyze API endpoints and security implementation
• Review UI components and user experience
• Check for architectural consistency and best practices
• Provide comprehensive feedback and recommendations

Summary

This PR introduces a well-architected authorization system with proper feature flagging, comprehensive testing, and good separation of concerns. The implementation follows SpiceDB best practices and provides a smooth migration path.

Key Strengths ✅

1. Excellent Feature Flag Design

• Clean ENABLE_AUTHZ feature flag that gracefully degrades
• When disabled, maintains current behavior (no breaking changes)
• Clear migration path without disrupting existing functionality

2. Solid SpiceDB Schema Design

• Well-documented schema with clear role hierarchy (spicedb/schema.zed:16-80)
• Proper separation of org-level vs project-level permissions
• Good naming conventions following SpiceDB best practices

3. Comprehensive Testing Strategy

• Extensive unit tests for all authorization functions
• Proper mocking of SpiceDB client
• Test coverage for both enabled/disabled authz states

4. Thoughtful Security Architecture

• Returns 404 instead of 403 when authz is enabled to avoid information disclosure (agents-manage-api/src/middleware/project-access.ts:104-111)
• Proper bypass logic for system users and API keys
• Atomic role changes using SpiceDB transactions

Areas for Improvement & Considerations

1. Critical: Race Condition in Role Changes

Severity: High

The changeProjectRole function has a potential race condition:

// packages/agents-core/src/auth/authz/sync.ts:175-219
await spice.promises.writeRelationships({
  updates: [
    { operation: RELATIONSHIP_OPERATION_DELETE, ... }, // Delete old role
    { operation: RELATIONSHIP_OPERATION_TOUCH, ... },  // Add new role
  ]
});

Issue: Between DELETE and TOUCH operations, the user temporarily has no project access, which could cause permission checks to fail if they occur during this window.

Recommendation: Consider using SpiceDB preconditions or implementing this as separate operations with proper error handling, or document this as an acceptable brief inconsistency.

2. Missing Migration Strategy

Severity: Medium

The sync script (scripts/sync-spicedb.sh) only syncs organization memberships but doesn't grant project-level access:

# Line 21: "Does NOT grant project-level access (org admins will do this manually)"

Concerns:

• When authz is first enabled, existing org members might suddenly lose project access
• No automated way to preserve current implicit access patterns
• Risk of service disruption during migration

Recommendations:

• Add a migration option to grant existing org members appropriate project roles
• Consider a project_legacy_member role for backwards compatibility during transition
• Provide clear documentation for the migration process

3. API Design: Inconsistent Error Handling

Severity: Medium

In projectMembers.ts, the endpoints return different errors when authz is disabled:

• List endpoint: Returns empty array (line 81)
• Write endpoints: Throw 400 error (line 136)

Recommendation: Consider consistent behavior - either all operations should work in a limited fashion or all should return errors when authz is disabled.

4. Performance: Missing Caching Strategy

Severity: Low-Medium

Permission checks hit SpiceDB on every request without caching:

// packages/agents-core/src/auth/authz/client.ts:44-75
export async function checkPermission(params: {...}): Promise<boolean> {
  // Direct SpiceDB call with minimizeLatency consistency
}

Recommendations:

• Consider implementing a short-lived cache for permission results
• Use SpiceDB's atExactSnapshot consistency for cacheable scenarios
• Add metrics to monitor permission check latency and frequency

5. UI/UX: Limited Error Messaging

Severity: Low

The access management UI doesn't provide clear feedback when operations fail or when authz is disabled.

Recommendations:

• Add loading states and error boundaries in access management components
• Show clear messaging when project access features are unavailable
• Consider progressive disclosure of advanced permission features

6. Architecture: Mixed Permission Patterns

Severity: Low

The codebase now has two permission patterns:

1. Legacy: Direct role checks in middleware
2. New: SpiceDB-based checks

Recommendation: Consider creating a unified permission interface that abstracts whether authz is enabled, making the codebase more maintainable.

Security Assessment ✅

• Authentication bypass: Properly handles system users and API keys
• Information disclosure: Uses 404 instead of 403 when appropriate
• RBAC implementation: Follows principle of least privilege
• Input validation: Proper validation of user IDs and roles
• Audit trail: SpiceDB provides built-in relationship tracking

Performance Considerations

• Database load: Additional SpiceDB calls on every permission check
• Network latency: Consider connection pooling for SpiceDB client
• Monitoring: Add observability for authorization performance

Breaking Changes Assessment

✅ No breaking changes when feature flag is disabled
⚠️ Potential access disruption during initial migration

Final Recommendation

This is a well-designed authorization system that demonstrates good architectural thinking. The main concerns are around migration strategy and the potential race condition in role changes.

Suggested next steps:

1. Address the role change race condition
2. Develop a comprehensive migration plan with project access preservation
3. Add performance monitoring and caching strategy
4. Create documentation for operators managing the authorization system

The implementation is ready for deployment with the above considerations addressed.

---