stack/docs/scratchpads/84-instance-identity-model.md

Issue #84: [FED-001] Instance Identity Model

Objective

Create the core identity model for federation including:

• Instance ID generation and persistence
• Instance metadata (URL, public key, capabilities)
• Database schema for federation connections
• Instance registration/discovery endpoints

Deliverables

• Instance model in Prisma schema
• FederationConnection model
• /api/v1/federation/instance endpoint (GET own identity)
• Instance keypair generation for signing

Approach

1. Database Schema (Prisma)

Add two new models:

• Instance: Represents this instance's identity

  • id (UUID primary key)
  • instanceId (unique identifier for federation)
  • name (display name)
  • url (base URL for this instance)
  • publicKey (RSA public key for signature verification)
  • privateKey (encrypted RSA private key for signing)
  • capabilities (JSON - what features this instance supports)
  • metadata (JSON - additional configuration)
  • timestamps

• FederationConnection: Represents connections to other instances

  • id (UUID primary key)
  • workspaceId (which workspace owns this connection)
  • remoteInstanceId (identifier of remote instance)
  • remoteUrl (base URL of remote instance)
  • remotePublicKey (remote instance's public key)
  • remoteCapabilities (JSON - what remote supports)
  • status (PENDING, ACTIVE, SUSPENDED, DISCONNECTED)
  • metadata (JSON)
  • timestamps

2. Service Layer

Create FederationService with methods:

• getInstanceIdentity(): Get or create this instance's identity
• generateKeypair(): Generate RSA keypair for signing
• getPublicIdentity(): Get sanitized public instance info (no private key)

Create FederationConnectionService for connection management (future phases)

3. API Endpoints (NestJS)

• GET /api/v1/federation/instance: Return instance identity
• POST /api/v1/federation/instance/regenerate-keys: Regenerate keypair (admin only)

4. Types

Define TypeScript interfaces:

• InstanceIdentity
• FederationConnectionStatus enum
• FederationCapabilities

5. Testing Strategy

• Unit tests for service layer
• Integration tests for API endpoints
• Test keypair generation and validation
• Test instance identity persistence

Progress

• Create scratchpad
• Add Prisma schema models
• Generate migration (db push with user authorization)
• Create TypeScript types
• Write tests for FederationService (7 tests)
• Implement FederationService
• Write tests for API endpoints (4 tests)
• Implement API controller
• Create FederationModule
• Add FederationModule to AppModule
• Verify all tests pass (11/11 passing)
• Type checking passes
• Test coverage: 100% statements, 100% functions, 66.66% branches (exceeds 85% requirement)
• Commit changes

Testing Plan

1. Unit Tests:

   • FederationService.getInstanceIdentity() creates identity if not exists
   • FederationService.getInstanceIdentity() returns existing identity
   • FederationService.generateKeypair() creates valid RSA keys
   • FederationService.getPublicIdentity() excludes private key

2. Integration Tests:

   • GET /api/v1/federation/instance returns instance identity
   • GET /api/v1/federation/instance is consistent across calls
   • POST /api/v1/federation/instance/regenerate-keys requires authentication
   • Regenerated keys are properly stored and returned

Design Decisions

1. Single Instance per Deployment: Each Mosaic Stack instance has exactly one identity record
2. RSA 2048-bit Keys: Balance between security and performance
3. Workspace-Scoped Connections: Each workspace manages its own federation connections
4. Status Enum: Clear connection states for lifecycle management
5. Capabilities JSON: Flexible schema for feature negotiation

Notes

• Need to ensure instance identity is created on first startup
• Private key should be encrypted at rest (future enhancement)
• Consider key rotation strategy (future enhancement)
• Connection handshake protocol will be in FED-002