Server routes and authentication

Every route authenticates through ports.identity.authenticate; the package guards its own routes and expects no host middleware (the demo's session middleware only makes sure a session exists; it is not what protects the routes). A null user answers 401 „Nicht angemeldet“ on API routes. The websocket upgrade of /collab/:id succeeds first by default, and a socket whose user is null is closed with code 4401 right after; with the module option collab.authenticateUpgrade the upgrade itself is refused with HTTP 401 (see Auth notes).

Routes

The AI routes are rate limited per user (sliding window, in memory, per process): exceeding it answers 429 „Zu viele KI-Anfragen, bitte kurz warten“ with Retry-After.

Filtering the mounted routes

installEditorServer mounts every route of serverRoutesOf(ports, { ai }) whose port is present. A host that serves some of these paths itself (for example /api/editor/assets/* from its own asset studio) passes routes, a function from the route table to the routes that are mounted; it can drop or reorder routes. The RouteDef type (method, path, port, handler) is exported from @skaile/forge-editor/server/nitro. The websocket is not part of the table; the default keeps every route.

installEditorServer(nitroApp, {
  ports,
  collab: false,
  routes: routes => routes.filter(route => !route.path.startsWith('/api/editor/assets')),
})

A host that drops the asset routes answers GET /api/editor/assets/:id/:name itself (media elements request that URL) and gives the client a backend whose assets.upload returns the URL of its own route.

Settings route status codes

/api/editor/settings:

Auth notes

• Websocket authentication (default). The upgrade to /collab/:id always succeeds (HTTP 101). Hocuspocus then authenticates the connection from the upgrade request's headers, so the session cookie authenticates the socket like any same-origin request, and from the client's token: clients that cannot send cookies pass token to the collaboration prop (a string or an async function; it becomes the HocuspocusProvider token) and authenticate receives it as request.token next to the headers. A client without a user gets a permission-denied answer and its socket is closed with code 4401 (not an HTTP 401).
• Rejecting at the upgrade (collab.authenticateUpgrade: true; Nuxt: the module option, installEditorServer: collab: { authenticateUpgrade: true }). The route calls authenticate({ headers }) (no token) before the upgrade; a null user answers HTTP 401 and no websocket is opened, otherwise the user is passed to the connection and not authenticated a second time. Use it when every client authenticates by cookie or other request headers; a client that identifies itself only by collaboration.token cannot connect then, because the token is only sent after the socket is open. authorize still runs per document in both modes.
• Document-level authorization (who may open which document) is the host's decision: authenticate returns the user, and authorize(user, id) decides per document on connect (null rejects, { readOnly: true } makes the connection read-only). Without authorize the websocket route passes any authenticated user to Hocuspocus for any document name.
• Asset URLs are guarded too; media elements send the session cookie.