feat(#94): implement spoke configuration UI

Implements the final piece of M7-Federation - the spoke configuration UI
that allows administrators to configure their local instance's federation
capabilities and settings.

Backend Changes:
- Add UpdateInstanceDto with validation for name, capabilities, and metadata
- Implement FederationService.updateInstanceConfiguration() method
- Add PATCH /api/v1/federation/instance endpoint to FederationController
- Add audit logging for configuration updates
- Add tests for updateInstanceConfiguration (5 new tests, all passing)

Frontend Changes:
- Create SpokeConfigurationForm component with PDA-friendly design
- Create /federation/settings page with configuration management
- Add regenerate keypair functionality with confirmation dialog
- Extend federation API client with updateInstanceConfiguration and regenerateInstanceKeys
- Add comprehensive tests (10 tests, all passing)

Design Decisions:
- Admin-only access via AdminGuard
- Never expose private key in API responses (security)
- PDA-friendly language throughout (no demanding terms)
- Clear visual hierarchy with read-only and editable fields
- Truncated public key with copy button for usability
- Confirmation dialog for destructive key regeneration

All tests passing:
- Backend: 13/13 federation service tests passing
- Frontend: 10/10 SpokeConfigurationForm tests passing
- TypeScript compilation: passing
- Linting: passing
- PDA-friendliness: verified

This completes M7-Federation. All federation features are now implemented.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

apps/api/src/federation/audit.service.ts

@@ -25,6 +25,25 @@ export class FederationAuditService {
     });
   }
 
+  /**
+   * Log instance configuration update (system-level operation)
+   * Logged to application logs for security audit trail
+   */
+  logInstanceConfigurationUpdate(
+    userId: string,
+    instanceId: string,
+    updates: Record<string, unknown>
+  ): void {
+    this.logger.log({
+      event: "FEDERATION_INSTANCE_CONFIG_UPDATED",
+      userId,
+      instanceId,
+      updates,
+      timestamp: new Date().toISOString(),
+      securityEvent: true,
+    });
+  }
+
   /**
    * Log federated authentication initiation
    */

apps/api/src/federation/dto/instance.dto.ts

@@ -0,0 +1,46 @@
+/**
+ * Instance Configuration DTOs
+ *
+ * Data Transfer Objects for instance configuration API.
+ */
+
+import { IsString, IsBoolean, IsOptional, IsObject, ValidateNested } from "class-validator";
+import { Type } from "class-transformer";
+
+/**
+ * DTO for federation capabilities
+ */
+export class FederationCapabilitiesDto {
+  @IsBoolean()
+  supportsQuery!: boolean;
+
+  @IsBoolean()
+  supportsCommand!: boolean;
+
+  @IsBoolean()
+  supportsEvent!: boolean;
+
+  @IsBoolean()
+  supportsAgentSpawn!: boolean;
+
+  @IsString()
+  protocolVersion!: string;
+}
+
+/**
+ * DTO for updating instance configuration
+ */
+export class UpdateInstanceDto {
+  @IsOptional()
+  @IsString()
+  name?: string;
+
+  @IsOptional()
+  @ValidateNested()
+  @Type(() => FederationCapabilitiesDto)
+  capabilities?: FederationCapabilitiesDto;
+
+  @IsOptional()
+  @IsObject()
+  metadata?: Record<string, unknown>;
+}

apps/api/src/federation/federation.controller.spec.ts

@@ -8,6 +8,7 @@ import { FederationController } from "./federation.controller";
 import { FederationService } from "./federation.service";
 import { FederationAuditService } from "./audit.service";
 import { ConnectionService } from "./connection.service";
+import { FederationAgentService } from "./federation-agent.service";
 import { AuthGuard } from "../auth/guards/auth.guard";
 import { AdminGuard } from "../auth/guards/admin.guard";
 import { FederationConnectionStatus } from "@prisma/client";
@@ -88,6 +89,14 @@ describe("FederationController", () => {
             handleIncomingConnectionRequest: vi.fn(),
           },
         },
+        {
+          provide: FederationAgentService,
+          useValue: {
+            spawnAgentOnRemote: vi.fn(),
+            getAgentStatus: vi.fn(),
+            killAgentOnRemote: vi.fn(),
+          },
+        },
       ],
     })
       .overrideGuard(AuthGuard)

apps/api/src/federation/federation.controller.ts

@@ -4,7 +4,18 @@
  * API endpoints for instance identity and federation management.
  */
 
-import { Controller, Get, Post, UseGuards, Logger, Req, Body, Param, Query } from "@nestjs/common";
+import {
+  Controller,
+  Get,
+  Post,
+  Patch,
+  UseGuards,
+  Logger,
+  Req,
+  Body,
+  Param,
+  Query,
+} from "@nestjs/common";
 import { FederationService } from "./federation.service";
 import { FederationAuditService } from "./audit.service";
 import { ConnectionService } from "./connection.service";
@@ -22,6 +33,7 @@ import {
   DisconnectConnectionDto,
   IncomingConnectionRequestDto,
 } from "./dto/connection.dto";
+import { UpdateInstanceDto } from "./dto/instance.dto";
 import type { SpawnAgentCommandPayload } from "./types/federation-agent.types";
 import { FederationConnectionStatus } from "@prisma/client";
 
@@ -68,6 +80,36 @@ export class FederationController {
     return result;
   }
 
+  /**
+   * Update instance configuration
+   * Requires system administrator privileges
+   * Allows updating name, capabilities, and metadata
+   * Returns public identity only (private key never exposed in API)
+   */
+  @Patch("instance")
+  @UseGuards(AuthGuard, AdminGuard)
+  async updateInstanceConfiguration(
+    @Req() req: AuthenticatedRequest,
+    @Body() dto: UpdateInstanceDto
+  ): Promise<PublicInstanceIdentity> {
+    if (!req.user) {
+      throw new Error("User not authenticated");
+    }
+
+    this.logger.log(`Admin user ${req.user.id} updating instance configuration`);
+
+    const result = await this.federationService.updateInstanceConfiguration(dto);
+
+    // Audit log for security compliance
+    const auditData: Record<string, unknown> = {};
+    if (dto.name !== undefined) auditData.name = dto.name;
+    if (dto.capabilities !== undefined) auditData.capabilities = dto.capabilities;
+    if (dto.metadata !== undefined) auditData.metadata = dto.metadata;
+    this.auditService.logInstanceConfigurationUpdate(req.user.id, result.instanceId, auditData);
+
+    return result;
+  }
+
   /**
    * Initiate a connection to a remote instance
    * Requires authentication

apps/api/src/federation/federation.service.spec.ts

@@ -228,4 +228,126 @@ describe("FederationService", () => {
       expect(result).toHaveProperty("instanceId");
     });
   });
+
+  describe("updateInstanceConfiguration", () => {
+    it("should update instance name", async () => {
+      // Arrange
+      const updatedInstance = { ...mockInstance, name: "Updated Instance" };
+      vi.spyOn(service, "getInstanceIdentity").mockResolvedValue({
+        ...mockInstance,
+        privateKey: mockDecryptedPrivateKey,
+      });
+      vi.spyOn(prismaService.instance, "update").mockResolvedValue(updatedInstance);
+
+      // Act
+      const result = await service.updateInstanceConfiguration({ name: "Updated Instance" });
+
+      // Assert
+      expect(prismaService.instance.update).toHaveBeenCalledWith({
+        where: { id: mockInstance.id },
+        data: { name: "Updated Instance" },
+      });
+      expect(result.name).toBe("Updated Instance");
+      expect(result).not.toHaveProperty("privateKey");
+    });
+
+    it("should update instance capabilities", async () => {
+      // Arrange
+      const newCapabilities = {
+        supportsQuery: true,
+        supportsCommand: false,
+        supportsEvent: true,
+        supportsAgentSpawn: false,
+        protocolVersion: "1.0",
+      };
+      const updatedInstance = { ...mockInstance, capabilities: newCapabilities };
+      vi.spyOn(service, "getInstanceIdentity").mockResolvedValue({
+        ...mockInstance,
+        privateKey: mockDecryptedPrivateKey,
+      });
+      vi.spyOn(prismaService.instance, "update").mockResolvedValue(updatedInstance);
+
+      // Act
+      const result = await service.updateInstanceConfiguration({ capabilities: newCapabilities });
+
+      // Assert
+      expect(prismaService.instance.update).toHaveBeenCalledWith({
+        where: { id: mockInstance.id },
+        data: { capabilities: newCapabilities },
+      });
+      expect(result.capabilities).toEqual(newCapabilities);
+    });
+
+    it("should update instance metadata", async () => {
+      // Arrange
+      const newMetadata = { description: "Test description", region: "us-west-2" };
+      const updatedInstance = { ...mockInstance, metadata: newMetadata };
+      vi.spyOn(service, "getInstanceIdentity").mockResolvedValue({
+        ...mockInstance,
+        privateKey: mockDecryptedPrivateKey,
+      });
+      vi.spyOn(prismaService.instance, "update").mockResolvedValue(updatedInstance);
+
+      // Act
+      const result = await service.updateInstanceConfiguration({ metadata: newMetadata });
+
+      // Assert
+      expect(prismaService.instance.update).toHaveBeenCalledWith({
+        where: { id: mockInstance.id },
+        data: { metadata: newMetadata },
+      });
+      expect(result.metadata).toEqual(newMetadata);
+    });
+
+    it("should update multiple fields at once", async () => {
+      // Arrange
+      const updates = {
+        name: "Updated Instance",
+        capabilities: {
+          supportsQuery: false,
+          supportsCommand: false,
+          supportsEvent: false,
+          supportsAgentSpawn: false,
+          protocolVersion: "1.0",
+        },
+        metadata: { description: "Updated" },
+      };
+      const updatedInstance = { ...mockInstance, ...updates };
+      vi.spyOn(service, "getInstanceIdentity").mockResolvedValue({
+        ...mockInstance,
+        privateKey: mockDecryptedPrivateKey,
+      });
+      vi.spyOn(prismaService.instance, "update").mockResolvedValue(updatedInstance);
+
+      // Act
+      const result = await service.updateInstanceConfiguration(updates);
+
+      // Assert
+      expect(prismaService.instance.update).toHaveBeenCalledWith({
+        where: { id: mockInstance.id },
+        data: updates,
+      });
+      expect(result.name).toBe("Updated Instance");
+      expect(result.capabilities).toEqual(updates.capabilities);
+      expect(result.metadata).toEqual(updates.metadata);
+    });
+
+    it("should not expose private key in response", async () => {
+      // Arrange
+      const updatedInstance = { ...mockInstance, name: "Updated" };
+      vi.spyOn(service, "getInstanceIdentity").mockResolvedValue({
+        ...mockInstance,
+        privateKey: mockDecryptedPrivateKey,
+      });
+      vi.spyOn(prismaService.instance, "update").mockResolvedValue(updatedInstance);
+
+      // Act
+      const result = await service.updateInstanceConfiguration({ name: "Updated" });
+
+      // Assert - SECURITY: Verify private key is NOT in response
+      expect(result).not.toHaveProperty("privateKey");
+      expect(result).toHaveProperty("publicKey");
+      expect(result).toHaveProperty("instanceId");
+    });
+  });
 });

apps/api/src/federation/federation.service.ts

@@ -104,6 +104,46 @@ export class FederationService {
     return publicIdentity;
   }
 
+  /**
+   * Update instance configuration
+   * Allows updating name, capabilities, and metadata
+   * Returns public identity only (no private key exposure)
+   */
+  async updateInstanceConfiguration(updates: {
+    name?: string;
+    capabilities?: FederationCapabilities;
+    metadata?: Record<string, unknown>;
+  }): Promise<PublicInstanceIdentity> {
+    const instance = await this.getInstanceIdentity();
+
+    // Build update data object
+    const data: Prisma.InstanceUpdateInput = {};
+
+    if (updates.name !== undefined) {
+      data.name = updates.name;
+    }
+
+    if (updates.capabilities !== undefined) {
+      data.capabilities = updates.capabilities as Prisma.JsonObject;
+    }
+
+    if (updates.metadata !== undefined) {
+      data.metadata = updates.metadata as Prisma.JsonObject;
+    }
+
+    const updatedInstance = await this.prisma.instance.update({
+      where: { id: instance.id },
+      data,
+    });
+
+    this.logger.log(`Instance configuration updated: ${JSON.stringify(updates)}`);
+
+    // Return public identity only (security fix)
+    const identity = this.mapToInstanceIdentity(updatedInstance);
+    const { privateKey: _privateKey, ...publicIdentity } = identity;
+    return publicIdentity;
+  }
+
   /**
    * Create a new instance identity
    */