Anonymous run api access sessions

[amikofalvy]

No description provided.

[changeset-bot]

⚠️ No Changeset found

Latest commit: e52fd3a

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 15, 2026 6:23pm
agents-eval-api	Ready	Preview, Comment	Jan 15, 2026 6:23pm
agents-manage-api	Ready	Preview, Comment	Jan 15, 2026 6:23pm
agents-manage-ui	Ready	Preview, Comment	Jan 15, 2026 6:23pm
agents-run-api	Ready	Preview, Comment	Jan 15, 2026 6:23pm

[claude]

Claude finished @amikofalvy's task —— View job

---

Code Review: Anonymous Run API Access Sessions

Review Progress:

• Understand the feature scope and implementation
• Review authentication and authorization changes
• Analyze database schema changes
• Evaluate API design and security implications
• Review documentation updates
• Provide comprehensive feedback and recommendations

✅ Summary

This PR implements anonymous user sessions using Better Auth's anonymous plugin, enabling public-facing widgets to provide stable user identity without requiring authentication. The implementation follows a well-designed dual authentication pattern: API Key (for project scope) + Session Token (for user scope).

🎯 Strengths

Excellent Architecture

• Clear separation of concerns: Run API allows anonymous sessions, Manage API rejects them
• Dual auth pattern: API key for project context + session token for user identity is elegant
• Comprehensive spec documentation: The anonymous-user-tokens.md spec is thorough and well-structured
• Proper security model: Server-managed sessions with cryptographic signing prevent impersonation

Clean Implementation

• Middleware design: Clean separation between API key validation and session validation
• Principal abstraction: Well-defined Principal type with proper isAnonymous handling
• Database schema: Minimal, appropriate addition of isAnonymous boolean field

⚠️ Areas for Improvement

Critical Security Considerations

1. validateSession Error Handling (agents-run-api/src/middleware/api-key-auth.ts:145-148):

   } catch (error) {
     logger.debug({ error }, 'Session validation failed');
     return null;
   }

   Issue: All session validation errors are silently swallowed. This could mask critical security issues.
   Recommendation: Add error categorization:

   } catch (error) {
     if (error.message?.includes('expired') || error.message?.includes('invalid')) {
       logger.debug({ error }, 'Expected session validation failure');
     } else {
       logger.warn({ error }, 'Unexpected session validation error');
     }
     return null;
   }

2. Development Environment Bypass (agents-run-api/src/middleware/api-key-auth.ts:382-417):

   if (isDev) {
     // ... bypass authentication
   }

   Issue: Development mode bypasses session validation entirely, which could hide integration issues.
   Recommendation: Allow session validation to run in development mode but fall back gracefully on failure.

API Design & Consistency

3. Inconsistent Auth Header Usage:

   • Documentation shows both X-API-Key + Authorization: Bearer <session> (new pattern)
   • Code also supports Authorization: Bearer <api_key> (backward compatibility)
   • UI examples still use x-api-key header alongside apiKey field

   Recommendation:

   • Standardize on X-API-Key + Authorization: Bearer <session> for new implementations
   • Add deprecation timeline for mixed patterns
   • Update UI examples to use consistent pattern

4. Missing Session Expiration Handling (agents-docs/_snippets/auth/RunApiAuthModes.mdx:56-71):

   if (!session.data) {
     const result = await authClient.signIn.anonymous();
   }

   Issue: No handling of expired sessions - only checks for missing sessions.
   Recommendation: Add session refresh logic:

   let session = await authClient.getSession();
   if (!session.data || isSessionExpired(session.data)) {
     const result = await authClient.signIn.anonymous();
     session = { data: result.data };
   }

Documentation & Testing

5. Missing Error Scenarios: Documentation doesn't cover important error cases:

   • Session token expired
   • Rate limiting exceeded
   • CORS/origin validation failures

   Recommendation: Add error handling examples in documentation.

6. Anonymous User Data Retention: Spec mentions "indefinite retention" but lacks:

   • Privacy compliance considerations
   • Data cleanup strategies
   • GDPR/CCPA implications for anonymous users

   Recommendation: Add privacy section to spec addressing data retention policies.

Implementation Gaps

7. Rate Limiting: No mention of rate limiting for anonymous users, who could potentially abuse the system.
   Recommendation: Implement per-session or per-IP rate limiting for anonymous users.

8. Cross-Device Session Sync: Spec mentions each device gets separate sessions, but there's no mechanism for users to link devices or transfer sessions.
   Recommendation: Consider adding an optional session transfer mechanism for user convenience.

🔧 Minor Issues

9. Type Safety (agents-run-api/src/types/execution-context.ts:15):

   isAnonymous: boolean;

   The isAnonymous field is redundant when type already indicates this. Consider removing for cleaner interface.

10. Logging Consistency: Some logs use distinctId, others use principalId for the same concept. Standardize terminology.

🚀 Future Enhancements

11. Account Linking: The spec mentions this as future work, but consider how to preserve conversation history when anonymous users decide to create accounts.

12. Analytics Integration: While distinctId is well-designed for analytics, consider adding standardized analytics events for session lifecycle (created, expired, linked).

✅ Overall Assessment

This is a high-quality implementation of a complex feature. The dual authentication pattern is elegant and secure. The separation between Run API (allows anonymous) and Manage API (requires authentication) is clean and well-implemented.

Primary concerns are around error handling robustness and API consistency. The security model is sound, but error scenarios need more thorough handling.

Recommendation: Address the critical error handling and API consistency issues before merging, but the overall architecture and implementation are excellent.

---

Definition of Done Check

• ✅ Anonymous plugin enabled in Better Auth
• ✅ Database migration for isAnonymous field
• ✅ Session token validation in Run API middleware
• ✅ Dual auth enforcement (API key + session)
• ✅ Principal abstraction implemented
• ❓ Session refresh handling (needs improvement)

Priority: Fix error handling (#1, #2) and API consistency (#3, #4) before merge.