Communication protocol between Universe Shell and modules via window.postMessage.

postMessage Protocol

Modules communicate with the Universe Shell via the browser's window.postMessage API. This is the bridge between the parent window (Shell) and the iframe (your module).

Message Types

Module → Shell

Message Type	Description	Payload
`REQUEST_AUTH_SESSION`	Request JWT tokens from Shell	none
`navigate`	Navigate Shell to a path	`{ path: string }`

Shell → Module

Message Type	Description	Payload
`AUTH_SESSION`	JWT tokens for Supabase	`{ access_token, refresh_token }`

Flow: Authentication

// Module sends (on mount):
window.parent.postMessage(
  { type: 'REQUEST_AUTH_SESSION' },
  '*'
);
 
// Shell responds:
iframe.contentWindow.postMessage(
  {
    type: 'AUTH_SESSION',
    payload: {
      access_token: 'eyJhbGciOiJIUzI1NiIs...',
      refresh_token: 'v1.abc123...',
    },
  },
  '*'
);

// Module triggers Shell navigation:
window.parent.postMessage(
  { type: 'navigate', path: '/admin/modules' },
  '*'
);
 
// Shell handles:
window.addEventListener('message', (event) => {
  if (event.data?.type === 'navigate') {
    router.push(event.data.path);
  }
});

URL Parameters

The Shell passes context via iframe URL query parameters:

Parameter	Type	Description
`org_id`	UUID	Organization ID for the current tenant

Example iframe URL:

https://my-module.vercel.app?org_id=550e8400-e29b-41d4-a716-446655440000

Security Notes

Messages use '*' as target origin in the current implementation
For enhanced security, validate event.origin against trusted Shell domains
Never trust message data without validation
JWT tokens are short-lived; Supabase handles refresh automatically

postMessage Protocol

postMessage Protocol

Message Types

Module → Shell

Shell → Module

Flow: Authentication

Flow: Navigation

URL Parameters

Security Notes

On this page