Docs bridge
Route: /docs-bridge
The docs bridge is a silent authentication relay used by the documentation site
(docs.mushimushi.dev) to access Mushi APIs on behalf of a logged-in user — for
example, to populate a live code snippet with your real API key, or to show
project-specific setup instructions.
You will never navigate here directly. The docs site opens /docs-bridge as a popup
or iframe, the bridge posts a token back, and the popup closes automatically.
How it works
- The docs site detects that it needs a Mushi session token.
- It opens
app.mushimushi.dev/docs-bridge?nonce=<one-time-nonce>&returnOrigin=<docs-origin>as a popup. - The bridge page:
- Reads the
?nonce=and?returnOrigin=query parameters. - Calls
supabase.auth.refreshSession()to ensure the token is fresh. - Posts the access token to the opener via
window.postMessage(origin-checked againstreturnOrigin). - Closes itself 500ms later.
- Reads the
- The docs site receives the token and uses it for a single API call, then discards it.
Status messages
The bridge page shows a minimal status card while running:
| Status | Meaning |
|---|---|
| Connecting… | Retrieving session and preparing to post |
| Docs sync connected | Token posted successfully — the popup will close |
| Sign in first | No active Mushi session — log in at app.mushimushi.dev first |
| Missing nonce | The ?nonce= parameter was absent — the docs site sent a malformed URL |
| Invalid origin | returnOrigin is not an allowed docs origin |
| Can’t talk back to docs window | The opener window was closed before the token could be posted |
Security
- The bridge validates
returnOriginagainst an allow-list of Mushi-owned docs origins. An attacker cannot use this route to steal tokens by pointingreturnOriginto an arbitrary domain. - The
nonceis a one-time value generated by the docs site per request. - No Mushi API calls are made — the bridge only refreshes the Supabase session token.
Related pages
Last updated on