feat(#93): implement agent spawn via federation
Implements FED-010: Agent Spawn via Federation feature that enables spawning and managing Claude agents on remote federated Mosaic Stack instances via COMMAND message type. Features: - Federation agent command types (spawn, status, kill) - FederationAgentService for handling agent operations - Integration with orchestrator's agent spawner/lifecycle services - API endpoints for spawning, querying status, and killing agents - Full command routing through federation COMMAND infrastructure - Comprehensive test coverage (12/12 tests passing) Architecture: - Hub → Spoke: Spawn agents on remote instances - Command flow: FederationController → FederationAgentService → CommandService → Remote Orchestrator - Response handling: Remote orchestrator returns agent status/results - Security: Connection validation, signature verification Files created: - apps/api/src/federation/types/federation-agent.types.ts - apps/api/src/federation/federation-agent.service.ts - apps/api/src/federation/federation-agent.service.spec.ts Files modified: - apps/api/src/federation/command.service.ts (agent command routing) - apps/api/src/federation/federation.controller.ts (agent endpoints) - apps/api/src/federation/federation.module.ts (service registration) - apps/orchestrator/src/api/agents/agents.controller.ts (status endpoint) - apps/orchestrator/src/api/agents/agents.module.ts (lifecycle integration) Testing: - 12/12 tests passing for FederationAgentService - All command service tests passing - TypeScript compilation successful - Linting passed Refs #93 Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
Jason Woltje
@@ -5,6 +5,7 @@ This directory contains shared guards and decorators for workspace-based permiss
|
||||
## Overview
|
||||
|
||||
The permission system provides:
|
||||
|
||||
- **Workspace isolation** via Row-Level Security (RLS)
|
||||
- **Role-based access control** (RBAC) using workspace member roles
|
||||
- **Declarative permission requirements** using decorators
|
||||
@@ -18,6 +19,7 @@ Located in `../auth/guards/auth.guard.ts`
|
||||
Verifies user authentication and attaches user data to the request.
|
||||
|
||||
**Sets on request:**
|
||||
|
||||
- `request.user` - Authenticated user object
|
||||
- `request.session` - User session data
|
||||
|
||||
@@ -26,23 +28,27 @@ Verifies user authentication and attaches user data to the request.
|
||||
Validates workspace access and sets up RLS context.
|
||||
|
||||
**Responsibilities:**
|
||||
|
||||
1. Extracts workspace ID from request (header, param, or body)
|
||||
2. Verifies user is a member of the workspace
|
||||
3. Sets the current user context for RLS policies
|
||||
4. Attaches workspace context to the request
|
||||
|
||||
**Sets on request:**
|
||||
|
||||
- `request.workspace.id` - Validated workspace ID
|
||||
- `request.user.workspaceId` - Workspace ID (for backward compatibility)
|
||||
|
||||
**Workspace ID Sources (in priority order):**
|
||||
|
||||
1. `X-Workspace-Id` header
|
||||
2. `:workspaceId` URL parameter
|
||||
3. `workspaceId` in request body
|
||||
|
||||
**Example:**
|
||||
|
||||
```typescript
|
||||
@Controller('tasks')
|
||||
@Controller("tasks")
|
||||
@UseGuards(AuthGuard, WorkspaceGuard)
|
||||
export class TasksController {
|
||||
@Get()
|
||||
@@ -57,23 +63,26 @@ export class TasksController {
|
||||
Enforces role-based access control using workspace member roles.
|
||||
|
||||
**Responsibilities:**
|
||||
|
||||
1. Reads required permission from `@RequirePermission()` decorator
|
||||
2. Fetches user's role in the workspace
|
||||
3. Checks if role satisfies the required permission
|
||||
4. Attaches role to request for convenience
|
||||
|
||||
**Sets on request:**
|
||||
|
||||
- `request.user.workspaceRole` - User's role in the workspace
|
||||
|
||||
**Must be used after AuthGuard and WorkspaceGuard.**
|
||||
|
||||
**Example:**
|
||||
|
||||
```typescript
|
||||
@Controller('admin')
|
||||
@Controller("admin")
|
||||
@UseGuards(AuthGuard, WorkspaceGuard, PermissionGuard)
|
||||
export class AdminController {
|
||||
@RequirePermission(Permission.WORKSPACE_ADMIN)
|
||||
@Delete('data')
|
||||
@Delete("data")
|
||||
async deleteData() {
|
||||
// Only ADMIN or OWNER can execute
|
||||
}
|
||||
@@ -88,14 +97,15 @@ Specifies the minimum permission level required for a route.
|
||||
|
||||
**Permission Levels:**
|
||||
|
||||
| Permission | Allowed Roles | Use Case |
|
||||
|------------|--------------|----------|
|
||||
| `WORKSPACE_OWNER` | OWNER | Critical operations (delete workspace, transfer ownership) |
|
||||
| `WORKSPACE_ADMIN` | OWNER, ADMIN | Administrative functions (manage members, settings) |
|
||||
| `WORKSPACE_MEMBER` | OWNER, ADMIN, MEMBER | Standard operations (create/edit content) |
|
||||
| `WORKSPACE_ANY` | All roles including GUEST | Read-only or basic access |
|
||||
| Permission | Allowed Roles | Use Case |
|
||||
| ------------------ | ------------------------- | ---------------------------------------------------------- |
|
||||
| `WORKSPACE_OWNER` | OWNER | Critical operations (delete workspace, transfer ownership) |
|
||||
| `WORKSPACE_ADMIN` | OWNER, ADMIN | Administrative functions (manage members, settings) |
|
||||
| `WORKSPACE_MEMBER` | OWNER, ADMIN, MEMBER | Standard operations (create/edit content) |
|
||||
| `WORKSPACE_ANY` | All roles including GUEST | Read-only or basic access |
|
||||
|
||||
**Example:**
|
||||
|
||||
```typescript
|
||||
@RequirePermission(Permission.WORKSPACE_ADMIN)
|
||||
@Post('invite')
|
||||
@@ -109,6 +119,7 @@ async inviteMember(@Body() inviteDto: InviteDto) {
|
||||
Parameter decorator to extract the validated workspace ID.
|
||||
|
||||
**Example:**
|
||||
|
||||
```typescript
|
||||
@Get()
|
||||
async getTasks(@Workspace() workspaceId: string) {
|
||||
@@ -121,6 +132,7 @@ async getTasks(@Workspace() workspaceId: string) {
|
||||
Parameter decorator to extract the full workspace context.
|
||||
|
||||
**Example:**
|
||||
|
||||
```typescript
|
||||
@Get()
|
||||
async getTasks(@WorkspaceContext() workspace: { id: string }) {
|
||||
@@ -135,6 +147,7 @@ Located in `../auth/decorators/current-user.decorator.ts`
|
||||
Extracts the authenticated user from the request.
|
||||
|
||||
**Example:**
|
||||
|
||||
```typescript
|
||||
@Post()
|
||||
async create(@CurrentUser() user: any, @Body() dto: CreateDto) {
|
||||
@@ -153,7 +166,7 @@ import { WorkspaceGuard, PermissionGuard } from "../common/guards";
|
||||
import { Workspace, Permission, RequirePermission } from "../common/decorators";
|
||||
import { CurrentUser } from "../auth/decorators/current-user.decorator";
|
||||
|
||||
@Controller('resources')
|
||||
@Controller("resources")
|
||||
@UseGuards(AuthGuard, WorkspaceGuard, PermissionGuard)
|
||||
export class ResourcesController {
|
||||
@Get()
|
||||
@@ -164,17 +177,13 @@ export class ResourcesController {
|
||||
|
||||
@Post()
|
||||
@RequirePermission(Permission.WORKSPACE_MEMBER)
|
||||
async create(
|
||||
@Workspace() workspaceId: string,
|
||||
@CurrentUser() user: any,
|
||||
@Body() dto: CreateDto
|
||||
) {
|
||||
async create(@Workspace() workspaceId: string, @CurrentUser() user: any, @Body() dto: CreateDto) {
|
||||
// Members and above can create
|
||||
}
|
||||
|
||||
@Delete(':id')
|
||||
@Delete(":id")
|
||||
@RequirePermission(Permission.WORKSPACE_ADMIN)
|
||||
async delete(@Param('id') id: string) {
|
||||
async delete(@Param("id") id: string) {
|
||||
// Only admins can delete
|
||||
}
|
||||
}
|
||||
@@ -185,24 +194,32 @@ export class ResourcesController {
|
||||
Different endpoints can have different permission requirements:
|
||||
|
||||
```typescript
|
||||
@Controller('projects')
|
||||
@Controller("projects")
|
||||
@UseGuards(AuthGuard, WorkspaceGuard, PermissionGuard)
|
||||
export class ProjectsController {
|
||||
@Get()
|
||||
@RequirePermission(Permission.WORKSPACE_ANY)
|
||||
async list() { /* Anyone can view */ }
|
||||
async list() {
|
||||
/* Anyone can view */
|
||||
}
|
||||
|
||||
@Post()
|
||||
@RequirePermission(Permission.WORKSPACE_MEMBER)
|
||||
async create() { /* Members can create */ }
|
||||
async create() {
|
||||
/* Members can create */
|
||||
}
|
||||
|
||||
@Patch('settings')
|
||||
@Patch("settings")
|
||||
@RequirePermission(Permission.WORKSPACE_ADMIN)
|
||||
async updateSettings() { /* Only admins */ }
|
||||
async updateSettings() {
|
||||
/* Only admins */
|
||||
}
|
||||
|
||||
@Delete()
|
||||
@RequirePermission(Permission.WORKSPACE_OWNER)
|
||||
async deleteProject() { /* Only owner */ }
|
||||
async deleteProject() {
|
||||
/* Only owner */
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
@@ -211,17 +228,19 @@ export class ProjectsController {
|
||||
The workspace ID can be provided in multiple ways:
|
||||
|
||||
**Via Header (Recommended for SPAs):**
|
||||
|
||||
```typescript
|
||||
// Frontend
|
||||
fetch('/api/tasks', {
|
||||
fetch("/api/tasks", {
|
||||
headers: {
|
||||
'Authorization': 'Bearer <token>',
|
||||
'X-Workspace-Id': 'workspace-uuid',
|
||||
}
|
||||
})
|
||||
Authorization: "Bearer <token>",
|
||||
"X-Workspace-Id": "workspace-uuid",
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
**Via URL Parameter:**
|
||||
|
||||
```typescript
|
||||
@Get(':workspaceId/tasks')
|
||||
async getTasks(@Param('workspaceId') workspaceId: string) {
|
||||
@@ -230,6 +249,7 @@ async getTasks(@Param('workspaceId') workspaceId: string) {
|
||||
```
|
||||
|
||||
**Via Request Body:**
|
||||
|
||||
```typescript
|
||||
@Post()
|
||||
async create(@Body() dto: { workspaceId: string; name: string }) {
|
||||
@@ -240,6 +260,7 @@ async create(@Body() dto: { workspaceId: string; name: string }) {
|
||||
## Row-Level Security (RLS)
|
||||
|
||||
When `WorkspaceGuard` is applied, it automatically:
|
||||
|
||||
1. Calls `setCurrentUser(userId)` to set the RLS context
|
||||
2. All subsequent database queries are automatically filtered by RLS policies
|
||||
3. Users can only access data in workspaces they're members of
|
||||
@@ -249,10 +270,12 @@ When `WorkspaceGuard` is applied, it automatically:
|
||||
## Testing
|
||||
|
||||
Tests are provided for both guards:
|
||||
|
||||
- `workspace.guard.spec.ts` - WorkspaceGuard tests
|
||||
- `permission.guard.spec.ts` - PermissionGuard tests
|
||||
|
||||
**Run tests:**
|
||||
|
||||
```bash
|
||||
npm test -- workspace.guard.spec
|
||||
npm test -- permission.guard.spec
|
||||
|
||||
Reference in New Issue
Block a user