Feat/inkeep slack app v2

[victor-inkeep]

Slack integration for Inkeep Agents with workspace installation, user account linking via Nango, and slash command support. I added a modular "Work Apps" architecture for future integrations.

API Authentication Pattern: Session Token Flow

How are authenticated API calls are made from Slack commands? We are using the user's session token:

Flow Overview

1. User links Slack account via Nango OAuth flow
2. Session token is captured from useAuthSession() and stored in Nango connection metadata
3. Slash commands retrieve token from connection metadata and use it for API calls

Implementation
Frontend captures session token during linking (slack-provider.tsx):

const { session } = useAuthSession();const { sessionToken } = await slackApi.createConnectSession({  userId: user.id,  sessionToken: session?.token,  // Pass current session token  sessionExpiresAt: session?.expiresAt,});
Backend stores token in Nango metadata (slack.ts):
app.post('/connect', async (c) => {  const { userId, sessionToken, sessionExpiresAt } = body;    // Store for retrieval after Nango OAuth completes  pendingSessionTokens.set(userId, { token: sessionToken, ... });});

API client uses Bearer token for requests (api-client.ts):

export class SlackApiClient {  private get headers(): Record<string, string> {    return {      'Content-Type': 'application/json',      Authorization: `Bearer ${this.sessionToken}`,    };  }  async listProjects(): Promise<PaginatedResponse<Project>> {    return this.request('GET', `/manage/tenants/${this.tenantId}/projects`);  }}

Commands use the client (commands/index.ts):

const client = createSlackApiClient(connection);  // Gets token from connectionconst result = await client.listProjects();

Features

• Workspace Installation: OAuth flow to install Slack app to workspaces
• User Account Linking: Connect Slack users to Inkeep accounts via Nango
• Slash Commands: /inkeep link|status|list|logout|help (subject to change)
• Work Apps UI: New modular architecture at /work-apps with Slack management dashboard
• State Management: TanStack Query for server state, Zustand for client state
• Local DB Preview: Mock localStorage database for development (prep for PostgreSQL)

Test Plan
[ ] Install Slack app to workspace via OAuth
[ ] Link user account through Nango flow
[ ] Verify /inkeep list returns projects using session token auth
[ ] Test session refresh on reconnection
[ ] Verify disconnect clears connection properly

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5e61b1d

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-api	Ready	Preview, Comment	Jan 28, 2026 8:18pm
agents-manage-ui	Ready	Preview, Comment	Jan 28, 2026 8:18pm

1 Skipped Deployment

Project	Deployment	Review	Updated (UTC)
agents-docs	Skipped		Jan 28, 2026 8:18pm

[claude]

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

---

Staff Engineer Code Review - Slack Integration v2

Conducting comprehensive architectural and code quality review for the Slack integration feature.

Review Tasks:

• Analyze overall architecture and Work Apps modular design
• Review session token authentication flow and security considerations
• Evaluate database schema and state management patterns
• Review API routes and client implementation
• Assess UI components and user experience
• Check error handling and edge cases
• Evaluate scalability and extensibility
• Review testing coverage and patterns

Review Summary

This PR introduces a comprehensive Slack integration with a modular "Work Apps" architecture. While the implementation is functionally sound, there are several critical security concerns and architectural considerations that need to be addressed.

🚨 Critical Security Issues

1. Session Token Storage in Third-Party Service (HIGH)

Location: agents-api/src/domains/manage/routes/slack.ts:362-367, agents-manage-ui/src/features/slack/context/slack-provider.tsx:186-194

The current implementation stores Inkeep session tokens in Nango connection metadata, which introduces significant security risks:

// Storing sensitive session tokens in external service
inkeep_session_token: pendingSession.token,
inkeep_session_expires_at: pendingSession.expiresAt,

Issues:

• Session tokens are stored in a third-party service (Nango)
• No guarantee of encryption at rest in Nango
• Creates unnecessary dependency on external service for security-critical data
• Potential for token exposure through Nango's admin interfaces or logs

Recommendation:

• Store session tokens in your own database with proper encryption
• Use connection ID as a foreign key to link to your internal session store
• Implement token refresh mechanism that doesn't rely on external storage

2. In-Memory Session Storage Without Persistence (MEDIUM)

Location: agents-api/src/domains/manage/routes/slack.ts:42-55

const pendingSessionTokens = new Map<string, { token: string; expiresAt: string; createdAt: number }>();

Issues:

• Memory-based storage will lose all pending sessions on service restart
• No persistence layer for session state during OAuth flow
• Could lead to failed user connections during deployments

Recommendation:

• Move to Redis or database-backed session storage
• Implement proper cleanup and expiration policies

3. Insufficient Request Validation (MEDIUM)

Location: agents-api/src/domains/manage/routes/slack.ts:392-397

if (env.SLACK_SIGNING_SECRET) {
  if (!verifySlackRequest(env.SLACK_SIGNING_SECRET, body, timestamp, signature)) {
    // ... error handling
  }
}

Issues:

• Request verification is conditional on environment variable presence
• No validation when signing secret is missing
• Commands could be executed without proper authentication in misconfigured environments

Recommendation:

• Make request verification mandatory for all Slack endpoints
• Fail fast if signing secret is not configured
• Add comprehensive logging for security events

🏗️ Architectural Concerns

4. Local Database Implementation is Over-Engineered (MEDIUM)

Location: agents-manage-ui/src/features/slack/db/local-db.ts

The local database implementation (574+ lines) creates unnecessary complexity:

Issues:

• Complex localStorage abstraction when simple state management would suffice
• Audit logging in frontend (unnecessary for local development data)
• Sophisticated querying capabilities not needed for development mocking
• Creates maintenance burden with minimal benefit

Recommendation:

• Simplify to basic Zustand store for development
• Remove audit logging from frontend
• Use server state management (TanStack Query) for real data

5. Work Apps Architecture Needs Extension Points (LOW)

Location: agents-manage-ui/src/features/work-apps/types.ts:19-81

Current implementation hardcodes all future integrations:

export const WORK_APPS_CONFIG: Record<WorkAppId, Omit<WorkApp, 'status' | 'installUrl' | 'dashboardUrl'>> = {
  slack: { /* config */ },
  github: { /* config */ },
  discord: { /* config */ },
  // ... all future apps hardcoded
};

Recommendation:

• Create plugin-based architecture for work apps
• Allow dynamic registration of integrations
• Separate core framework from specific integrations

✅ Positive Aspects

Strong Error Handling

The Slack API client includes comprehensive error handling with specific error types and user-friendly messages.

Modular Architecture Foundation

The Work Apps concept provides a good foundation for future integrations, though it needs refinement for extensibility.

Comprehensive State Management

Good use of TanStack Query for server state and Zustand for client state, following React best practices.

🧪 Testing Gaps

Critical Missing: No tests found for any Slack integration code. For a feature of this complexity and security sensitivity, comprehensive testing is essential:

Required Tests:

• Unit tests for authentication flows
• Integration tests for Slack OAuth callback handling
• Security tests for request verification
• API client error handling tests
• UI component tests

📋 Required Actions Before Merge

High Priority (Must Fix)

1. Move session token storage to internal database with proper encryption
2. Make Slack request verification mandatory - remove conditional behavior
3. Add comprehensive test coverage for all Slack functionality
4. Implement persistent session storage (Redis/database) instead of in-memory Map

Medium Priority (Should Fix)

1. Simplify local database implementation - reduce complexity for development tooling
2. Add proper error boundaries in React components for better UX
3. Implement session refresh mechanism that doesn't depend on external storage

Low Priority (Consider)

1. Refactor Work Apps for extensibility - move toward plugin architecture
2. Add security event logging for audit trails
3. Consider rate limiting for Slack webhook endpoints

🎯 Verdict

This PR introduces valuable functionality but has critical security issues that must be resolved before merging. The session token storage pattern is particularly concerning and could expose user authentication data.

The architectural foundation is solid, but the implementation needs security hardening and testing before production deployment.

---