Aller au contenu principal

Hub Protocol Flow

Complete flow documentation for Data Pod ↔ External Intelligence Services communication

Overview​

The Hub Protocol is the standardized contract governing communication between the Synap Core OS (Data Pod) and External Intelligence Services (available via the marketplace). This protocol enables:

  • ✅ Security: Mutual authentication and time-limited tokens
  • ✅ Type Safety: Zod schemas for runtime validation
  • ✅ Traceability: Complete audit trail of all access
  • ✅ Sovereignty: The Data Pod has complete control over data access

Note: External Intelligence Services are third-party services that can be connected via the marketplace. They provide specialized AI capabilities while respecting data sovereignty.

Complete Flow Example​

Let's follow a complex use case: "Plan my trip to Lisbon for May."

Protocol Endpoints​

1. generateAccessToken​

Purpose: Generate a temporary access token for the external service

Request:

{
  requestId: string; // UUID
  scope: string[]; // ['preferences', 'calendar', 'tasks', ...]
  expiresIn: number; // 60-300 seconds (1-5 minutes)
}

Response:

{
  token: string; // JWT token
  expiresAt: number; // Unix timestamp (milliseconds)
  requestId: string; // UUID of the request
}

2. requestData​

Purpose: Allow the external service to request read-only data

Request:

{
  token: string; // JWT token from generateAccessToken
  scope: string[]; // Data types to retrieve
  filters?: {
    dateRange?: { start: string; end: string };
    entityTypes?: string[];
    limit?: number; // 1-1000, default 100
    offset?: number; // default 0
  };
}

Response:

{
  userId: string;
  requestId: string;
  data: {
    preferences?: UserPreferences;
    calendar?: CalendarEvent[];
    notes?: NoteSummary[];
    tasks?: TaskSummary[];
    // ... other data types
  };
  metadata: {
    retrievedAt: string; // ISO timestamp
    scope: string[];
    recordCount: number;
  };
}

3. submitInsight​

Purpose: Allow the external service to submit a structured insight that will be transformed into events

Request:

{
  token: string; // JWT token
  insight: {
    version: '1.0';
    type: 'action_plan' | 'analysis' | 'suggestion';
    correlationId: string; // requestId
    actions: Array<{
      eventType: string; // e.g., 'project.creation.requested'
      data: Record<string, unknown>;
      requiresConfirmation?: boolean;
    }>;
    confidence: number; // 0-1
    reasoning: string;
  };
}

Response:

{
  success: boolean;
  requestId: string;
  eventIds: string[]; // UUIDs of created events
  eventsCreated: number;
  errors?: Array<{
    actionIndex: number;
    error: string;
  }>;
}

Security & Privacy​

Token Security​

  • Time-limited: Maximum 5 minutes validity
  • Scope-based: Service can only request authorized data
  • Non-reusable: Each token is tied to a unique request (requestId)
  • Audit trail: All token generation is logged

Data Confidentiality​

  • No persistent storage: External services receive data in memory only
  • Automatic cleanup: Data is garbage collected after processing
  • Anonymized logs: Error logs contain only IDs, never user content
  • Temporary cache: Maximum 60-second TTL for performance optimization

GDPR Compliance​

  • ✅ Right to be forgotten: User can revoke service access at any time
  • ✅ Data portability: All data remains in user's Data Pod
  • ✅ Transparency: User can view audit log of all service access
  • ✅ Minimization: Services only request strictly necessary data

Best Practices​

  1. Always validate tokens before processing requests
  2. Log all access for complete audit trail
  3. Use minimal scopes - only request what's needed
  4. Handle errors gracefully - return clear error messages
  5. Respect token expiration - never use expired tokens

Next: See Hub Protocol API Reference for complete API documentation.