docs: add Federation Architecture design document
Captures: - Peer-to-peer federation model (master/spoke) - Agent Federation Protocol (CONNECT, QUERY, COMMAND, EVENT, DISCONNECT) - Authentik integration for enterprise SSO and RBAC - Data sovereignty principles (query, don't replicate) - RBAC model with workspace/team hierarchy - Implementation phases targeting 0.1.0 MVP - Versioning policy (0.0.x dev, 0.1.0 MVP, 1.0.0 stable)
This commit is contained in:
Jason Woltje
@@ -70,4 +70,44 @@ When creating a new design document:
|
|||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
### [Federation Architecture](./federation-architecture.md)
|
||||||
|
|
||||||
|
**Status:** Design Phase
|
||||||
|
**Version:** 0.0.1
|
||||||
|
**Date:** 2025-01-29
|
||||||
|
|
||||||
|
Multi-instance federation enabling cross-organization collaboration, work/personal separation, and enterprise control with data sovereignty.
|
||||||
|
|
||||||
|
**Key Features:**
|
||||||
|
- Peer-to-peer federation (every instance can be master and/or spoke)
|
||||||
|
- Authentik integration for enterprise SSO and RBAC
|
||||||
|
- Agent Federation Protocol for cross-instance queries and commands
|
||||||
|
- Data sovereignty (query in place, never replicate)
|
||||||
|
- Single pane of glass aggregating multiple instances
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
### [Multi-Tenant RLS](./multi-tenant-rls.md)
|
||||||
|
|
||||||
|
**Status:** Implemented
|
||||||
|
**Version:** 1.0
|
||||||
|
**Date:** 2025-01-29
|
||||||
|
|
||||||
|
PostgreSQL Row-Level Security for workspace isolation and defense-in-depth multi-tenancy.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
When creating a new design document:
|
||||||
|
|
||||||
|
1. Copy the structure from an existing document
|
||||||
|
2. Use ASCII diagrams for architecture (keep them simple)
|
||||||
|
3. Include code examples in TypeScript
|
||||||
|
4. Specify database schema in SQL (PostgreSQL dialect)
|
||||||
|
5. Add implementation phases with clear milestones
|
||||||
|
6. Update this README with a summary
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
**Last Updated:** 2025-01-29
|
**Last Updated:** 2025-01-29
|
||||||
|
|||||||
848
docs/design/federation-architecture.md
Normal file
848
docs/design/federation-architecture.md
Normal file
@@ -0,0 +1,848 @@
|
|||||||
|
# Federation Architecture
|
||||||
|
|
||||||
|
**Version:** 0.0.1
|
||||||
|
**Status:** Design Phase
|
||||||
|
**Author:** Mosaic Stack Team
|
||||||
|
**Date:** 2025-01-29
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
1. [Problem Statement](#problem-statement)
|
||||||
|
2. [Architecture Overview](#architecture-overview)
|
||||||
|
3. [Identity & Authentication](#identity--authentication)
|
||||||
|
4. [Agent Federation Protocol](#agent-federation-protocol)
|
||||||
|
5. [RBAC Model](#rbac-model)
|
||||||
|
6. [Data Sovereignty](#data-sovereignty)
|
||||||
|
7. [Implementation Phases](#implementation-phases)
|
||||||
|
8. [Versioning](#versioning)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Problem Statement
|
||||||
|
|
||||||
|
### Use Cases
|
||||||
|
|
||||||
|
1. **Work/Personal Separation**
|
||||||
|
- Developer has personal projects at home and work projects at the office
|
||||||
|
- Data must stay in its respective environment
|
||||||
|
- Single pane of glass for unified visibility
|
||||||
|
|
||||||
|
2. **Enterprise Control**
|
||||||
|
- Organization runs their own Mosaic Stack instance
|
||||||
|
- Teams within the org have isolated workspaces
|
||||||
|
- IT controls access, audit, compliance
|
||||||
|
|
||||||
|
3. **Cross-Organization Collaboration**
|
||||||
|
- Partner companies need to share specific projects
|
||||||
|
- Guest access with limited permissions
|
||||||
|
- No data replication—query in place
|
||||||
|
|
||||||
|
### Requirements
|
||||||
|
|
||||||
|
- **Data Sovereignty** — Data stays where it's created, never crosses boundaries
|
||||||
|
- **Unified Control** — Single interface to view/manage multiple instances
|
||||||
|
- **Clean Severance** — Disconnect = lose access, no data to clean up
|
||||||
|
- **Enterprise Auth** — SSO, RBAC, audit trails
|
||||||
|
- **Peer-to-Peer** — Any instance can be both master and spoke
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architecture Overview
|
||||||
|
|
||||||
|
### Peer-to-Peer Federation Model
|
||||||
|
|
||||||
|
Every Mosaic Stack instance is a **peer** that can simultaneously act as:
|
||||||
|
- **Master** — Control and query downstream spokes
|
||||||
|
- **Spoke** — Expose capabilities to upstream masters
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────┐
|
||||||
|
│ ENTERPRISE │
|
||||||
|
│ (Corp HQ) │
|
||||||
|
└────────┬────────┘
|
||||||
|
│ speaks to
|
||||||
|
┌──────────────┼──────────────┐
|
||||||
|
▼ ▼ ▼
|
||||||
|
┌──────────┐ ┌──────────┐ ┌──────────┐
|
||||||
|
│ IT Dept │ │ Dev Team │ │ HR Dept │
|
||||||
|
└────┬─────┘ └────┬─────┘ └──────────┘
|
||||||
|
│ │
|
||||||
|
▼ ▼
|
||||||
|
┌──────────┐ ┌──────────┐
|
||||||
|
│ Jason │◄─►│ Mike │ ← peer sharing
|
||||||
|
│ (Work) │ │ (Work) │
|
||||||
|
└────┬─────┘ └──────────┘
|
||||||
|
│
|
||||||
|
│ speaks to (personal master)
|
||||||
|
▼
|
||||||
|
┌──────────┐
|
||||||
|
│ Jason │◄─► [Future: Family instance?]
|
||||||
|
│ (Home) │◄─► [Future: Trusted collaborator?]
|
||||||
|
└──────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### Component Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ IDENTITY PLANE │
|
||||||
|
│ (Authentik) │
|
||||||
|
├─────────────────────────────────────────────────────────────────┤
|
||||||
|
│ • Users (identities across instances) │
|
||||||
|
│ • Groups (teams, departments, roles) │
|
||||||
|
│ • Applications (Mosaic Stack instances) │
|
||||||
|
│ • Federation trust (OIDC/SAML between IdPs) │
|
||||||
|
└───────────────────────────┬─────────────────────────────────────┘
|
||||||
|
│ OIDC / SAML
|
||||||
|
┌───────────────────┼───────────────────┐
|
||||||
|
▼ ▼ ▼
|
||||||
|
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
|
||||||
|
│ Instance A │ │ Instance B │ │ Instance C │
|
||||||
|
│ (Home) │ │ (Work) │ │ (Partner) │
|
||||||
|
├───────────────┤ ├───────────────┤ ├───────────────┤
|
||||||
|
│ Agent Layer │ │ Agent Layer │ │ Agent Layer │
|
||||||
|
│ ┌───────────┐ │ │ ┌───────────┐ │ │ ┌───────────┐ │
|
||||||
|
│ │ Jarvis │ │ │ │ Jarvis │ │ │ │ Partner │ │
|
||||||
|
│ │ Prime │◄┼───┼─┤ Work │ │ │ │ Agent │ │
|
||||||
|
│ └───────────┘ │ │ └───────────┘ │ │ └───────────┘ │
|
||||||
|
├───────────────┤ ├───────────────┤ ├───────────────┤
|
||||||
|
│ Workspaces: │ │ Workspaces: │ │ Workspaces: │
|
||||||
|
│ • Personal │ │ • IT Ops │ │ • Shared Proj │
|
||||||
|
│ • Side Proj │ │ • Dev Team │ │ │
|
||||||
|
└───────────────┘ └───────────────┘ └───────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Identity & Authentication
|
||||||
|
|
||||||
|
### Authentik as Identity Provider
|
||||||
|
|
||||||
|
Authentik provides enterprise-grade identity management:
|
||||||
|
|
||||||
|
| Feature | Purpose |
|
||||||
|
|---------|---------|
|
||||||
|
| **OIDC/SAML** | Single sign-on across instances |
|
||||||
|
| **User Directory** | Centralized user management |
|
||||||
|
| **Groups** | Team/department organization |
|
||||||
|
| **RBAC** | Role-based access control |
|
||||||
|
| **Audit Logs** | Compliance and security tracking |
|
||||||
|
| **MFA** | Multi-factor authentication |
|
||||||
|
| **Federation** | Trust between external IdPs |
|
||||||
|
|
||||||
|
### Auth Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────────┐
|
||||||
|
│ Identity Provider (Authentik) │
|
||||||
|
├─────────────────────────────────────────────────────────────────┤
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────────┐ │
|
||||||
|
│ │ Users │ │ Groups │ │ Applications │ │
|
||||||
|
│ ├─────────────┤ ├─────────────┤ ├─────────────────────────┤ │
|
||||||
|
│ │ jason │ │ IT-Team │ │ mosaic-home │ │
|
||||||
|
│ │ mike │ │ Dev-Team │ │ mosaic-work-usc │ │
|
||||||
|
│ │ sarah │ │ Admins │ │ mosaic-partner-acme │ │
|
||||||
|
│ └─────────────┘ └─────────────┘ └─────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ ┌──────────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ Policies & Flows │ │
|
||||||
|
│ │ • Login flow (password + MFA) │ │
|
||||||
|
│ │ • OAuth2/OIDC scopes (profile, email, groups) │ │
|
||||||
|
│ │ • Conditional access (IP, device, time) │ │
|
||||||
|
│ │ • External IdP federation (Google, Azure AD) │ │
|
||||||
|
│ └──────────────────────────────────────────────────────────┘ │
|
||||||
|
└─────────────────────────────────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌───────────────────┼───────────────────┐
|
||||||
|
│ OIDC │ OIDC │ OIDC
|
||||||
|
▼ ▼ ▼
|
||||||
|
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||||
|
│ Mosaic Home │ │ Mosaic Work │ │ Mosaic Ext │
|
||||||
|
└─────────────┘ └─────────────┘ └─────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### OIDC Token Claims
|
||||||
|
|
||||||
|
Mosaic Stack expects these claims from the IdP:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"sub": "user-uuid-123",
|
||||||
|
"preferred_username": "jason",
|
||||||
|
"email": "jason@example.com",
|
||||||
|
"groups": ["IT-Team", "Dev-Team", "Admins"],
|
||||||
|
"roles": ["workspace:ws-123:owner", "workspace:ws-456:member"],
|
||||||
|
"aud": "mosaic-home",
|
||||||
|
"iss": "https://auth.example.com"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Cross-Instance Identity
|
||||||
|
|
||||||
|
When federating between instances with different IdPs:
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────┐ ┌─────────────────┐
|
||||||
|
│ Authentik A │◄── OIDC Trust ───►│ Authentik B │
|
||||||
|
│ (Home IdP) │ │ (Work IdP) │
|
||||||
|
└────────┬────────┘ └────────┬────────┘
|
||||||
|
│ │
|
||||||
|
│ │
|
||||||
|
▼ ▼
|
||||||
|
┌─────────────────┐ ┌─────────────────┐
|
||||||
|
│ Mosaic Home │ │ Mosaic Work │
|
||||||
|
│ │ │ │
|
||||||
|
│ User: jason │◄── Federation ───►│ User: jason │
|
||||||
|
│ (home identity)│ Protocol │ (work identity)│
|
||||||
|
└─────────────────┘ └─────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
**Identity Mapping:**
|
||||||
|
- Same email = same person (by convention)
|
||||||
|
- Explicit identity linking via federation protocol
|
||||||
|
- No implicit access—must be granted per instance
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Agent Federation Protocol
|
||||||
|
|
||||||
|
### Connection Lifecycle
|
||||||
|
|
||||||
|
```
|
||||||
|
┌────────────┐ ┌────────────┐
|
||||||
|
│ MASTER │ │ SPOKE │
|
||||||
|
│ (Home) │ │ (Work) │
|
||||||
|
└─────┬──────┘ └─────┬──────┘
|
||||||
|
│ │
|
||||||
|
│ 1. CONNECT (auth token + scopes) │
|
||||||
|
│───────────────────────────────────────►│
|
||||||
|
│ │
|
||||||
|
│ 2. CAPABILITIES (available APIs) │
|
||||||
|
│◄───────────────────────────────────────│
|
||||||
|
│ │
|
||||||
|
│ 3. QUERY / COMMAND (ongoing) │
|
||||||
|
│◄──────────────────────────────────────►│
|
||||||
|
│ │
|
||||||
|
│ 4. EVENT (push notifications) │
|
||||||
|
│◄───────────────────────────────────────│
|
||||||
|
│ │
|
||||||
|
│ 5. DISCONNECT (clean exit) │
|
||||||
|
│───────────────────────────────────────►│
|
||||||
|
│ │
|
||||||
|
```
|
||||||
|
|
||||||
|
### Message Types
|
||||||
|
|
||||||
|
#### 1. `CONNECT` — Establish Federation Trust
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "connect",
|
||||||
|
"version": "0.0.1",
|
||||||
|
"masterIdentity": {
|
||||||
|
"instanceId": "mosaic-home-jason",
|
||||||
|
"userId": "jason",
|
||||||
|
"instanceUrl": "https://mosaic.home.local"
|
||||||
|
},
|
||||||
|
"authToken": "oidc-access-token-or-api-key",
|
||||||
|
"requestedScopes": [
|
||||||
|
"calendar.read",
|
||||||
|
"calendar.write",
|
||||||
|
"tasks.read",
|
||||||
|
"tasks.write",
|
||||||
|
"agents.query",
|
||||||
|
"agents.command"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2. `CAPABILITIES` — Spoke Advertises Available APIs
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "capabilities",
|
||||||
|
"spokeIdentity": {
|
||||||
|
"instanceId": "mosaic-work-usc",
|
||||||
|
"instanceUrl": "https://mosaic.uscllc.com"
|
||||||
|
},
|
||||||
|
"grantedScopes": ["calendar.read", "tasks.read", "tasks.write"],
|
||||||
|
"deniedScopes": ["calendar.write", "agents.command"],
|
||||||
|
"availableCommands": [
|
||||||
|
{
|
||||||
|
"name": "tasks.list",
|
||||||
|
"description": "List tasks in workspace",
|
||||||
|
"params": { "workspaceId": "string", "status": "string?" }
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "tasks.create",
|
||||||
|
"description": "Create a new task",
|
||||||
|
"params": { "title": "string", "description": "string?" }
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "calendar.today",
|
||||||
|
"description": "Get today's calendar events",
|
||||||
|
"params": {}
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"availableQueries": [
|
||||||
|
{
|
||||||
|
"name": "status",
|
||||||
|
"description": "Get instance status",
|
||||||
|
"returns": "InstanceStatus"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "workspaces.list",
|
||||||
|
"description": "List accessible workspaces",
|
||||||
|
"returns": "Workspace[]"
|
||||||
|
}
|
||||||
|
],
|
||||||
|
"eventSubscriptions": [
|
||||||
|
"calendar.reminder",
|
||||||
|
"tasks.assigned",
|
||||||
|
"tasks.completed"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 3. `QUERY` — Read-Only Data Fetch
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "query",
|
||||||
|
"id": "q-abc123",
|
||||||
|
"name": "calendar.today",
|
||||||
|
"params": { "includeAllDay": true }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Response:**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "query.result",
|
||||||
|
"id": "q-abc123",
|
||||||
|
"success": true,
|
||||||
|
"data": [
|
||||||
|
{ "title": "Standup", "time": "09:00", "duration": 30 },
|
||||||
|
{ "title": "1:1 with Mike", "time": "14:00", "duration": 60 }
|
||||||
|
],
|
||||||
|
"provenance": {
|
||||||
|
"instanceId": "mosaic-work-usc",
|
||||||
|
"timestamp": "2025-01-29T14:30:00Z"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 4. `COMMAND` — Execute an Action
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "command",
|
||||||
|
"id": "c-def456",
|
||||||
|
"name": "tasks.create",
|
||||||
|
"params": {
|
||||||
|
"title": "Review PR #421",
|
||||||
|
"description": "Security review for auth changes",
|
||||||
|
"priority": 8,
|
||||||
|
"workspaceId": "ws-dev-team"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Sync Response:**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "command.result",
|
||||||
|
"id": "c-def456",
|
||||||
|
"success": true,
|
||||||
|
"data": {
|
||||||
|
"taskId": "task-789",
|
||||||
|
"url": "https://mosaic.uscllc.com/tasks/task-789"
|
||||||
|
},
|
||||||
|
"provenance": {
|
||||||
|
"instanceId": "mosaic-work-usc",
|
||||||
|
"timestamp": "2025-01-29T14:31:00Z"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Async Response (for long-running):**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "command.accepted",
|
||||||
|
"id": "c-def456",
|
||||||
|
"status": "pending",
|
||||||
|
"pollUrl": "/federation/status/c-def456",
|
||||||
|
"estimatedCompletion": "30s"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 5. `EVENT` — Push Notification from Spoke
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "event",
|
||||||
|
"name": "calendar.reminder",
|
||||||
|
"data": {
|
||||||
|
"title": "1:1 with Mike",
|
||||||
|
"startsIn": "15m",
|
||||||
|
"location": "Conference Room B"
|
||||||
|
},
|
||||||
|
"provenance": {
|
||||||
|
"instanceId": "mosaic-work-usc",
|
||||||
|
"timestamp": "2025-01-29T13:45:00Z"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 6. `DISCONNECT` — Clean Severance
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "disconnect",
|
||||||
|
"reason": "user-initiated",
|
||||||
|
"revokeToken": true,
|
||||||
|
"preserveHistory": false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Agent-to-Agent Communication
|
||||||
|
|
||||||
|
Masters can command spokes to execute agent tasks:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "command",
|
||||||
|
"id": "c-agent-001",
|
||||||
|
"name": "agents.spawn",
|
||||||
|
"params": {
|
||||||
|
"taskTitle": "Review today's tickets",
|
||||||
|
"taskDescription": "Check GLPI for new high-priority tickets",
|
||||||
|
"inputContext": {
|
||||||
|
"priority": "high",
|
||||||
|
"category": "network"
|
||||||
|
},
|
||||||
|
"callbackUrl": "https://mosaic.home.local/federation/callback/c-agent-001"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
The spoke agent executes the task and calls back with results:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"type": "callback",
|
||||||
|
"id": "c-agent-001",
|
||||||
|
"success": true,
|
||||||
|
"data": {
|
||||||
|
"ticketsFound": 3,
|
||||||
|
"tickets": [
|
||||||
|
{ "id": "GLPI-1234", "title": "Switch failure in Building A" },
|
||||||
|
{ "id": "GLPI-1235", "title": "VPN connectivity issues" },
|
||||||
|
{ "id": "GLPI-1236", "title": "Printer offline 3rd floor" }
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## RBAC Model
|
||||||
|
|
||||||
|
### Hierarchy
|
||||||
|
|
||||||
|
```
|
||||||
|
Instance
|
||||||
|
└── Workspace (like a Teams "Team")
|
||||||
|
├── Roles: owner, admin, member, viewer, guest
|
||||||
|
├── Teams (sub-groups within workspace)
|
||||||
|
│ └── Roles: owner, admin, member
|
||||||
|
├── Projects / Channels
|
||||||
|
│ └── Permissions (inherit or override)
|
||||||
|
└── Members (users or groups from IdP)
|
||||||
|
```
|
||||||
|
|
||||||
|
### Role Permissions Matrix
|
||||||
|
|
||||||
|
| Permission | Owner | Admin | Member | Viewer | Guest |
|
||||||
|
|------------|-------|-------|--------|--------|-------|
|
||||||
|
| View workspace | ✓ | ✓ | ✓ | ✓ | ✓* |
|
||||||
|
| Create content | ✓ | ✓ | ✓ | ✗ | ✗ |
|
||||||
|
| Edit content | ✓ | ✓ | ✓ | ✗ | ✗ |
|
||||||
|
| Delete content | ✓ | ✓ | ✗ | ✗ | ✗ |
|
||||||
|
| Manage members | ✓ | ✓ | ✗ | ✗ | ✗ |
|
||||||
|
| Manage teams | ✓ | ✓ | ✗ | ✗ | ✗ |
|
||||||
|
| Configure workspace | ✓ | ✗ | ✗ | ✗ | ✗ |
|
||||||
|
| Delete workspace | ✓ | ✗ | ✗ | ✗ | ✗ |
|
||||||
|
| Manage federation | ✓ | ✗ | ✗ | ✗ | ✗ |
|
||||||
|
|
||||||
|
*Guest: scoped to specific shared items only
|
||||||
|
|
||||||
|
### Federation RBAC
|
||||||
|
|
||||||
|
Cross-instance access is always scoped and limited:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"federation": {
|
||||||
|
"trustedInstances": [
|
||||||
|
{
|
||||||
|
"instanceId": "mosaic-work-usc",
|
||||||
|
"trustLevel": "verified",
|
||||||
|
"maxRole": "member",
|
||||||
|
"scopedWorkspaces": ["ws-shared-projects"],
|
||||||
|
"allowedCapabilities": ["tasks.read", "tasks.write", "calendar.read"],
|
||||||
|
"deniedCapabilities": ["admin.*", "federation.*"]
|
||||||
|
}
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key Constraints:**
|
||||||
|
- Federated users cannot exceed `maxRole` (e.g., member can't become admin)
|
||||||
|
- Access limited to `scopedWorkspaces` only
|
||||||
|
- Capabilities are explicitly allowlisted
|
||||||
|
- Admin/federation capabilities always denied by default
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Data Sovereignty
|
||||||
|
|
||||||
|
### Core Principles
|
||||||
|
|
||||||
|
1. **Data Residency** — Data lives where it's created, never crosses boundaries
|
||||||
|
2. **Query, Don't Replicate** — Master queries spoke, doesn't store results
|
||||||
|
3. **Provenance Tagging** — Every piece of data tagged with source instance
|
||||||
|
4. **Clean Exit** — Disconnect = lose access, no cleanup needed
|
||||||
|
|
||||||
|
### Data Flow
|
||||||
|
|
||||||
|
```
|
||||||
|
┌──────────────────────────────────────────────────────────────────┐
|
||||||
|
│ MASTER (Home) │
|
||||||
|
│ │
|
||||||
|
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||||
|
│ │ Aggregation Layer │ │
|
||||||
|
│ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────────────┐ │ │
|
||||||
|
│ │ │ Home Data │ │ Work Data │ │ Partner Data │ │ │
|
||||||
|
│ │ │ (stored) │ │ (queried) │ │ (queried) │ │ │
|
||||||
|
│ │ │ │ │ ⚡ live │ │ ⚡ live │ │ │
|
||||||
|
│ │ └─────────────┘ └──────┬──────┘ └──────────┬──────────┘ │ │
|
||||||
|
│ │ │ │ │ │
|
||||||
|
│ └──────────────────────────┼─────────────────────┼─────────────┘ │
|
||||||
|
│ │ │ │
|
||||||
|
└─────────────────────────────┼─────────────────────┼───────────────┘
|
||||||
|
│ │
|
||||||
|
┌─────────▼─────────┐ ┌────────▼────────┐
|
||||||
|
│ SPOKE (Work) │ │ SPOKE (Partner) │
|
||||||
|
│ Data stays here │ │ Data stays here │
|
||||||
|
└───────────────────┘ └─────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### What's Stored vs Queried
|
||||||
|
|
||||||
|
| Data Type | Home Instance | Work Instance | Notes |
|
||||||
|
|-----------|---------------|---------------|-------|
|
||||||
|
| Personal tasks | ✓ Stored | — | Only at home |
|
||||||
|
| Work tasks | Queried live | ✓ Stored | Never replicated |
|
||||||
|
| Personal calendar | ✓ Stored | — | Only at home |
|
||||||
|
| Work calendar | Queried live | ✓ Stored | Never replicated |
|
||||||
|
| Federation metadata | ✓ Stored | ✓ Stored | Connection config only |
|
||||||
|
| Query results cache | Ephemeral (5m TTL) | — | Optional, short-lived |
|
||||||
|
|
||||||
|
### Severance Procedure
|
||||||
|
|
||||||
|
When disconnecting from a spoke:
|
||||||
|
|
||||||
|
```
|
||||||
|
1. Master initiates DISCONNECT
|
||||||
|
2. Spoke revokes master's access token
|
||||||
|
3. Spoke removes master from trusted instances
|
||||||
|
4. Master removes spoke from connection list
|
||||||
|
5. All live queries fail immediately
|
||||||
|
6. No data cleanup needed—nothing was stored
|
||||||
|
|
||||||
|
Result:
|
||||||
|
- Master retains: its own data, federation config (marked disconnected)
|
||||||
|
- Spoke retains: its own data, audit log of the connection
|
||||||
|
- Neither has: the other's data
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Implementation Phases
|
||||||
|
|
||||||
|
### Phase 1: Foundation (v0.0.x)
|
||||||
|
|
||||||
|
**Goal:** Multi-instance awareness, basic federation protocol
|
||||||
|
|
||||||
|
**Deliverables:**
|
||||||
|
- [ ] Instance identity model (instanceId, URL, public key)
|
||||||
|
- [ ] Federation connection database schema
|
||||||
|
- [ ] Basic CONNECT/DISCONNECT protocol
|
||||||
|
- [ ] Manual connection setup (no auto-discovery)
|
||||||
|
- [ ] Query/Command message handling (stub)
|
||||||
|
|
||||||
|
**Testing:**
|
||||||
|
- Two local instances can connect
|
||||||
|
- Connection persists across restarts
|
||||||
|
- Disconnect cleans up properly
|
||||||
|
|
||||||
|
### Phase 2: Authentik Integration (v0.0.x)
|
||||||
|
|
||||||
|
**Goal:** Enterprise SSO with RBAC
|
||||||
|
|
||||||
|
**Deliverables:**
|
||||||
|
- [ ] Authentik OIDC provider setup guide
|
||||||
|
- [ ] BetterAuth Authentik adapter
|
||||||
|
- [ ] Group → Role mapping
|
||||||
|
- [ ] Multi-workspace session handling
|
||||||
|
- [ ] Audit logging for auth events
|
||||||
|
|
||||||
|
**Testing:**
|
||||||
|
- Login via Authentik works
|
||||||
|
- Groups map to roles correctly
|
||||||
|
- Session isolation between workspaces
|
||||||
|
|
||||||
|
### Phase 3: Federation Protocol (v0.0.x)
|
||||||
|
|
||||||
|
**Goal:** Full query/command capability
|
||||||
|
|
||||||
|
**Deliverables:**
|
||||||
|
- [ ] QUERY message type with response streaming
|
||||||
|
- [ ] COMMAND message type with async support
|
||||||
|
- [ ] EVENT subscription and delivery
|
||||||
|
- [ ] Capability negotiation
|
||||||
|
- [ ] Error handling and retry logic
|
||||||
|
|
||||||
|
**Testing:**
|
||||||
|
- Master can query spoke calendar
|
||||||
|
- Master can create tasks on spoke
|
||||||
|
- Events push from spoke to master
|
||||||
|
- Errors handled gracefully
|
||||||
|
|
||||||
|
### Phase 4: Single Pane of Glass (v0.1.0 MVP)
|
||||||
|
|
||||||
|
**Goal:** Unified dashboard showing all instances
|
||||||
|
|
||||||
|
**Deliverables:**
|
||||||
|
- [ ] Connection manager UI
|
||||||
|
- [ ] Aggregated calendar view
|
||||||
|
- [ ] Aggregated task view
|
||||||
|
- [ ] Instance status indicators
|
||||||
|
- [ ] Visual provenance tagging (color/icon per instance)
|
||||||
|
|
||||||
|
**Testing:**
|
||||||
|
- Dashboard shows data from multiple instances
|
||||||
|
- Clear visual distinction between sources
|
||||||
|
- Offline instance shows gracefully
|
||||||
|
|
||||||
|
### Phase 5: Agent Federation (v0.1.x)
|
||||||
|
|
||||||
|
**Goal:** Cross-instance agent coordination
|
||||||
|
|
||||||
|
**Deliverables:**
|
||||||
|
- [ ] Agent spawn command via federation
|
||||||
|
- [ ] Callback mechanism for results
|
||||||
|
- [ ] Agent status querying across instances
|
||||||
|
- [ ] Cross-instance task assignment
|
||||||
|
|
||||||
|
**Testing:**
|
||||||
|
- Home agent can spawn task on work instance
|
||||||
|
- Results callback works
|
||||||
|
- Agent health visible across instances
|
||||||
|
|
||||||
|
### Phase 6: Enterprise Features (v0.2.x)
|
||||||
|
|
||||||
|
**Goal:** Production-ready for organizations
|
||||||
|
|
||||||
|
**Deliverables:**
|
||||||
|
- [ ] Admin console for federation management
|
||||||
|
- [ ] Compliance audit reports
|
||||||
|
- [ ] Rate limiting and quotas
|
||||||
|
- [ ] Webhook integration
|
||||||
|
- [ ] Multi-region support
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Versioning
|
||||||
|
|
||||||
|
### Semantic Versioning Policy
|
||||||
|
|
||||||
|
| Version | Meaning |
|
||||||
|
|---------|---------|
|
||||||
|
| `0.0.x` | Active development, breaking changes expected, internal use only |
|
||||||
|
| `0.1.0` | **MVP** — First user-testable release, core features working |
|
||||||
|
| `0.x.y` | Pre-stable iteration, API may change with notice |
|
||||||
|
| `1.0.0` | Stable release, public API contract, breaking changes require major version |
|
||||||
|
|
||||||
|
### Version Milestones
|
||||||
|
|
||||||
|
| Version | Target | Features |
|
||||||
|
|---------|--------|----------|
|
||||||
|
| 0.0.1 | Design | This document |
|
||||||
|
| 0.0.5 | Foundation | Basic federation protocol |
|
||||||
|
| 0.0.10 | Auth | Authentik integration |
|
||||||
|
| 0.1.0 | **MVP** | Single pane of glass, basic federation |
|
||||||
|
| 0.2.0 | Agents | Cross-instance agent coordination |
|
||||||
|
| 0.3.0 | Enterprise | Admin console, compliance |
|
||||||
|
| 1.0.0 | Stable | Production-ready, API frozen |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Security Considerations
|
||||||
|
|
||||||
|
### Transport Security
|
||||||
|
|
||||||
|
- All federation traffic over TLS 1.3
|
||||||
|
- Certificate pinning for known instances (optional)
|
||||||
|
- mTLS for high-security deployments
|
||||||
|
|
||||||
|
### Authentication
|
||||||
|
|
||||||
|
- OIDC tokens with short expiry (1h)
|
||||||
|
- Refresh tokens with longer expiry (7d)
|
||||||
|
- API keys for service-to-service (no user context)
|
||||||
|
|
||||||
|
### Authorization
|
||||||
|
|
||||||
|
- Capability-based access control
|
||||||
|
- Explicit allowlists (deny by default)
|
||||||
|
- No implicit transitivity (A→B→C doesn't mean A→C)
|
||||||
|
|
||||||
|
### Audit
|
||||||
|
|
||||||
|
- All federation connections logged
|
||||||
|
- All queries/commands logged with user identity
|
||||||
|
- Retention configurable per compliance requirements
|
||||||
|
|
||||||
|
### Secrets
|
||||||
|
|
||||||
|
- Never log tokens or credentials
|
||||||
|
- Encrypt sensitive federation config at rest
|
||||||
|
- Rotate API keys periodically
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## API Endpoints
|
||||||
|
|
||||||
|
### Federation Management
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// List connected instances
|
||||||
|
GET /api/v1/federation/connections
|
||||||
|
Response: FederationConnection[]
|
||||||
|
|
||||||
|
// Initiate connection to spoke
|
||||||
|
POST /api/v1/federation/connect
|
||||||
|
{
|
||||||
|
"spokeUrl": "https://mosaic.work.example.com",
|
||||||
|
"authToken": "...",
|
||||||
|
"requestedScopes": ["calendar.read", "tasks.*"]
|
||||||
|
}
|
||||||
|
|
||||||
|
// Disconnect from spoke
|
||||||
|
DELETE /api/v1/federation/connections/:instanceId
|
||||||
|
|
||||||
|
// Get connection status
|
||||||
|
GET /api/v1/federation/connections/:instanceId/status
|
||||||
|
|
||||||
|
// Update connection scopes
|
||||||
|
PATCH /api/v1/federation/connections/:instanceId
|
||||||
|
{
|
||||||
|
"requestedScopes": ["calendar.*", "tasks.*"]
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Federated Queries
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Query a spoke
|
||||||
|
POST /api/v1/federation/query
|
||||||
|
{
|
||||||
|
"instanceId": "mosaic-work-usc",
|
||||||
|
"query": "calendar.today",
|
||||||
|
"params": { "includeAllDay": true }
|
||||||
|
}
|
||||||
|
|
||||||
|
// Execute command on spoke
|
||||||
|
POST /api/v1/federation/command
|
||||||
|
{
|
||||||
|
"instanceId": "mosaic-work-usc",
|
||||||
|
"command": "tasks.create",
|
||||||
|
"params": { "title": "Review PR", "priority": 8 }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Spoke Configuration (for instances accepting connections)
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// Get spoke settings
|
||||||
|
GET /api/v1/federation/spoke/settings
|
||||||
|
|
||||||
|
// Update spoke settings
|
||||||
|
PATCH /api/v1/federation/spoke/settings
|
||||||
|
{
|
||||||
|
"acceptConnections": true,
|
||||||
|
"allowedMasters": ["mosaic-home-jason"],
|
||||||
|
"defaultScopes": ["calendar.read", "tasks.read"],
|
||||||
|
"maxScopes": ["calendar.*", "tasks.*"]
|
||||||
|
}
|
||||||
|
|
||||||
|
// List connected masters
|
||||||
|
GET /api/v1/federation/spoke/masters
|
||||||
|
|
||||||
|
// Revoke master access
|
||||||
|
DELETE /api/v1/federation/spoke/masters/:instanceId
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Glossary
|
||||||
|
|
||||||
|
| Term | Definition |
|
||||||
|
|------|------------|
|
||||||
|
| **Instance** | A single Mosaic Stack deployment |
|
||||||
|
| **Master** | Instance that initiates connection and queries spoke |
|
||||||
|
| **Spoke** | Instance that accepts connections and serves data |
|
||||||
|
| **Peer** | An instance that can be both master and spoke |
|
||||||
|
| **Federation** | Network of connected Mosaic Stack instances |
|
||||||
|
| **Scope** | Permission to perform specific actions (e.g., `calendar.read`) |
|
||||||
|
| **Capability** | API endpoint exposed by a spoke |
|
||||||
|
| **Provenance** | Source attribution for data (which instance it came from) |
|
||||||
|
| **Severance** | Clean disconnection with no data cleanup required |
|
||||||
|
| **IdP** | Identity Provider (e.g., Authentik) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## References
|
||||||
|
|
||||||
|
- [Authentik Documentation](https://goauthentik.io/docs/)
|
||||||
|
- [OIDC Specification](https://openid.net/specs/openid-connect-core-1_0.html)
|
||||||
|
- [Multi-Tenant RLS Design](./multi-tenant-rls.md)
|
||||||
|
- [Agent Orchestration Design](./agent-orchestration.md)
|
||||||
|
- [Architecture Decisions](./architecture-decisions.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Open Questions
|
||||||
|
|
||||||
|
1. **Identity Linking:** How do we link the same person across instances with different IdPs?
|
||||||
|
2. **Conflict Resolution:** What happens if the same entity is modified on multiple instances?
|
||||||
|
3. **Offline Handling:** How long to cache spoke data when offline?
|
||||||
|
4. **Rate Limiting:** How to prevent spoke overload from aggressive masters?
|
||||||
|
5. **Discovery:** Should instances be discoverable, or always manual connection?
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Next Steps:**
|
||||||
|
1. Review and approve this design document
|
||||||
|
2. Create GitHub issues for Phase 1 tasks
|
||||||
|
3. Set up Authentik development instance
|
||||||
|
4. Begin federation protocol implementation
|
||||||
|
|
||||||
|
**Questions/Feedback:** Open an issue in `mosaic-stack` repo with label `federation`.
|
||||||
Reference in New Issue
Block a user