Start bridge (@tuturuuu/start-bridge)

​

Export map

​

Worker handler

import { createFunctionProxy } from '@tuturuuu/start-bridge/function-proxy';
import { createBridgeHandler } from '@tuturuuu/start-bridge/start/handler';
import { createBridgeStartHandler } from '@tuturuuu/start-bridge/start/server-entry';
import { proxy } from '../src/proxy';
import { endpoints } from '../src/runtime/api-registry.bridge.gen';

export default {
  fetch: createBridgeHandler<Env, ExecutionContext>({
    mounts: {
      app: 'meet',
      rootHosts: ['meet.tuturuuu.com'],
      mountHosts: ['tuturuuu.com'],
      basePath: '/meet',
    },
    start: createBridgeStartHandler(),
    serverFnBase: '/_serverFn',
    proxy,
    endpoints,
    functionBase: '/_serverFn',
    functionProxy: createFunctionProxy({ targetApp: 'meet' }),
    publicAssets,
    assets: (env) => env.ASSETS,
    centralApiOrigin: (env) => env.INTERNAL_WEB_API_ORIGIN ?? 'https://tuturuuu.com',
  }),
};

​

Registries and the unregistered-route check

{
  "appDir": "src/app",
  "stripSegments": { "[locale]": { "locale": "en" } },
  "api": { "out": "src/runtime/api-registry.bridge.gen.ts" },
  "pages": { "out": "src/runtime/page-registry.bridge.gen.ts" },
  "owned": { "api/build-info/route.ts": "src/native/api.server.ts" },
  "ignored": { "api/legacy/route.ts": "served by the central API" }
}

​

basePath contract

​

Shared session on the apex (proposal for security review)

​

Current model and the apex problems

• Each satellite holds a per-app access token in tuturuuu_app_session (target_app = that app; verifyAppSessionToken requires an exact match) plus tuturuuu_app_session_refresh, host-only at Path=/ on its subdomain.
• With sessionMode: 'supabase-first' and the root Supabase cookies (sb-<ref>-auth-token*, shared on .tuturuuu.com) present, refreshAppSessionForRequest already derives the app claims from Supabase, mints the access token in memory as Authorization: Bearer for that request, and then calls clearAppSessionCookie.
• On the apex, clearAppSessionCookie would expire tuturuuu_app_session, its refresh cookie and Web’s own tuturuuu_web_app_session (+ refresh) at Path=/ on every mounted-app request.
• Web’s createClient (packages/supabase/src/next/server.ts and request/server.ts, requestHasAppSessionAuth) switches to the isolated app-session client whenever a tuturuuu_app_session cookie is present, so any app writing that cookie at Path=/ on the apex drops Web’s Supabase session. If several apps wrote it, they would overwrite each other’s per-app token.

​

Decision required: a JavaScript-readable shared session on one origin

• an enforced CSP with per-response script nonces (createBridgeHandler({ csp }), requestNonce()) and Trusted Types, which is already mandatory before an app mounts on the apex;
• no inline event handlers or eval-style sinks, and dependency review for script injection;
• the decideOneOriginRequest gate (#6746) in front of every mount.

​

Proposed model (if accepted)

1. The shared apex session is the root Supabase session. Mounted apps derive their per-app claims per request (in-memory bearer, as today) and never write or clear tuturuuu_app_session* or tuturuuu_web_app_session* on the apex. The audience check stays per app; the Supabase JWT is validated on every request.
2. Mounted mode is decided by the bridge from the request URL only. The handler deletes any client-sent x-tuturuuu-app-base and sets its own from the resolved mount. Auth code must not trust that header on any route a client can reach without the bridge in front (direct Worker hosts, Web, or tests); the invariant below is enforced by the writers themselves.
3. The no-app-cookie invariant holds at every writer and clearer on the apex host: setAppSessionCookie, setAppSessionRefreshCookie, setWebAppSessionCookie, setWebAppSessionRefreshCookie, clearAppSessionCookie (including the MFA-redirect clear in packages/auth/src/proxy/index.ts), createSupabaseBackedAppSessionResponse, and the cross-app helpers in packages/auth/src/cross-app/server.ts. Each checks the response’s target host, not a request header. The satellite api/auth/refresh-app-session and api/auth/verify-app-token routes reject apex (mounted) calls before any write.
4. CSRF. Every unsafe, cookie-authenticated endpoint on the apex requires a same-origin Origin (or a CSRF token) and rejects Sec-Fetch-Site: cross-site; server functions keep Start’s CSRF middleware. Logout is a protected unsafe operation, not a GET.
5. Logout and refresh races. Logout signs the user out of the Supabase session, so it is global across Web and every mounted app by design. Concurrent tabs and Workers may refresh the same Supabase refresh token: rely on the project’s refresh-token reuse interval, never let a refresh response restore cookies after a sign-out (responses compare a session generation before writing Set-Cookie), and accept that an already issued access JWT stays valid until its expiry (bound the access-token lifetime accordingly; revocation-sensitive operations re-check the session).
6. Verification cost. Each mounted-app request validates the Supabase JWT (local with asymmetric keys; JWKS cached with rotation-aware refetch), refreshes when near expiry, and may run the MFA lookups the satellites already run. Measure the p95 on staging before cutover.
7. Subdomains keep today’s behaviour until each app’s cutover.

​

Code that must change (auth owner, after acceptance)

​

Page adapter

​

Runtime tag

​

Vite preset

const bridge = startBridgePreset({
  appRoot: import.meta.url,
  app: 'apps',
  navigation: 'document',
  shims: ['next/headers', 'next/server', 'next/navigation', 'next/link', 'next-intl'],
  serverOnlySpecifiers: ['@tuturuuu/satellite/auth'],
});
export default defineConfig(({ command }) => ({
  base: bridge.base,
  define: bridge.define,
  experimental: bridge.experimental,
  plugins: [voidPlugin(), tanstackStart(bridge.tanstackStart), react(), tailwindcss()],
  environments: { client: { define: bridge.clientDefine(command) } },
  resolve: { alias: bridge.alias },
}));

​

CI template

​

Verification