mono/packages/ui/docs/multi-tenant.md

Multi-Tenant via URL Architecture Options

Implementing multi-tenancy over the URL is a common pattern for SaaS applications. Here is an exploration of the available options, their applicability, and safety implications, focusing specifically on the Hono server architecture and Supabase database isolation.

1. Subdomain-Based Routing (Recommended)

Format: https://tenant_slug.yourdomain.com

How it works: The tenant is identified by extracting the subdomain from the request's hostname.

Applicability: Highly applicable and the industry standard for B2B SaaS. It provides the cleanest URL structure and visually assures users they are in their dedicated workspace.

Server Implementation (Hono):

• Add a global middleware early in the app.use chain that inspects the Host or X-Forwarded-Host header.
• Extract the subdomain (e.g., tenant_slug) and inject it into the request context (c.set('tenant', tenant_slug)).
• Infrastructure: Requires configuring a wildcard DNS record (*.yourdomain.com) and wildcard SSL certificates.

Safety:

• High. Cross-tenant data leakage via the UI is hard because the context is structurally tied to the origin.
• Cookies can be scoped to the specific subdomain, preventing Session/Auth token leakage to other tenants.

2. Path-Based Routing (URL Prefix)

Format: https://yourdomain.com/t/tenant_slug/ or https://yourdomain.com/tenant_slug/

How it works: The tenant ID is the first prefix segment of the URL path.

Applicability: Very common when you cannot manage wildcard subdomains or want a simpler infrastructure setup. Useful for B2C SaaS or mixed platforms.

Server Implementation (Hono):

• Hono allows route grouping and middleware scoping based on paths.
• Mount the API under a tenant prefix, e.g., app.use('/api/t/:tenantSlug/*', tenantMiddleware).
• The middleware extracts :tenantSlug from c.req.param('tenantSlug') and injects it into c.set('tenant', tenantSlug).
• This requires refactoring existing Hono route registrations (like app.route) to be nested under the path parameter.

Safety:

• Medium-High. The backend middleware must strictly validate the :tenantSlug parameter against the authenticated user's allowed tenants.
• Cookies are shared across the root domain. A compromised session on one tenant path can theoretically affect another if the user relies on path-scoping, which browsers handle inconsistently.

3. Query Parameter-Based Routing (Not Recommended)

Format: https://yourdomain.com/dashboard?tenant=tenant_slug

How it works: Every API call passes the tenant as a query parameter.

Safety:

• Low. Prone to state leakage.

---

Server & Database Security Architecture (Supabase)

Merely parsing the tenant from the URL does not make the application secure. The server must use the URL purely as context, and rely on the database for authorization.

1. Never Trust the URL for Auth: If a user navigates to tenant-b.domain.com but their session limits them to tenant-a, the server must reject the data access.

2. Middleware Pipeline: Your Hono server should have a distinct sequence in server/src/index.ts:

   • tenantMiddleware: Extracts tenant from URL/Host -> c.set('tenantId', id).
   • authMiddleware: Verifies the authentication JWT. Determines the user's ID.
   • authorizationMiddleware (Optional but recommended): Verifies if c.get('user') is a member of c.get('tenantId') via a quick Supabase check or decoded JWT claims.

3. Database Isolation using Supabase (RLS): The most robust way to ensure safety is pushing the multi-tenant logic down to Postgres via Row Level Security (RLS).

   Instead of modifying every query (.eq('tenant_id', tenantId)), use Postgres local variables:

   • When Hono handles a requested endpoint, generate a Supabase client using Service Role or standard Auth.
   • Before running queries, set the Postgres config context:

     await supabase.rpc('set_tenant_context', { _tenant_id: c.get('tenantId') });
     // Or raw query: set_config('app.current_tenant', '...', true);
     

   • Your RLS policies on tables simply do:

     CREATE POLICY "Tenant isolation" ON public.documents 
     USING (tenant_id = current_setting('app.current_tenant')::uuid);
     

   This ensures that even if you forget to add a .eq('tenant_id') to an API call, data leakage is impossible at the database engine level.

Deployment on Plesk (Apache Proxy to Node)

Since the application runs via an Apache proxy in a Plesk environment, the deployment implications vary significantly depending on the routing strategy:

For Subdomain-Based Routing

• Plesk Configuration: You must create a "Wildcard Subdomain" (*.yourdomain.com) in Plesk attached to the same proxy configuration as the main application.
• SSL Certificates: The Let's Encrypt extension in Plesk supports issuing Wildcard certificates, but this strictly requires DNS validation via API (e.g., Cloudflare) rather than standard HTTP validation.
• Apache Proxy Pass: Plesk's Apache to Node.js proxy preserves the original request host internally (ProxyPreserveHost On), so Hono will natively receive tenant.yourdomain.com in the Host header, alongside X-Forwarded-Host. No advanced .htaccess editing is required; you just assign the wildcard domain to the Node app correctly.

For Path-Based Routing

• Plesk Configuration: Requires zero structural changes to your Plesk or Apache setup. Everything remains under yourdomain.com which is already safely proxied to your application.
• SSL Certificates: Your existing single-domain SSL certificate handles everything automatically. No DNS API integration is needed.
• Apache Proxy Pass: Passes through normally; the backend Node application sees the full URI path and routes accordingly.

Conclusion

Since the frontend is not driving the structural isolation via an OrganizationProvider, the true source of truth must live in the Hono Server and Supabase Database.

For a robust architecture:

1. Choose either Subdomains (preferable) or Path Parameters for Hono routing.
2. Implement a unified tenantMiddleware in server/src/index.ts to extract and attach the context to the Hono c (Context).
3. Standardize on Supabase RLS with custom config variables to enforce hard data isolation, preventing accidental cross-tenant queries across all API routes.