page Workspacesandgateway {
  seo {
    title = "Workspaces and gateway"
    description = "Add applications, route domains, and implement safe SSO forward authentication."
    canonical = "https://wrnexusjs.dev/guides/workspaces-and-gateway"
  }
  view {
    <a href="#main" class="skip-link">Skip to content</a>
    <div class="docs-shell">
      <header class="topbar"><a class="brand" href="/"><span>W</span> WRNexusJS</a><nav aria-label="Primary"><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="https://component.wrnexusjs.dev/">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a></nav><div class="topbar-actions"><a class="preview-pill" href="/access">Preview · v0.8.1</a><button data-wire-theme-toggle class="theme-button" aria-label="Toggle color theme" title="Toggle color theme">◐</button></div></header>
      <div class="mobile-doc-nav"><details><summary>Browse documentation</summary><nav><a href="/getting-started">Get started</a><a href="/packages">Packages</a><a href="https://component.wrnexusjs.dev/">Components</a><a href="/language">Language</a><a href="/architecture">Architecture</a><a href="/tutorial">Tutorial</a><a href="/guides/project-structure">Guides</a><a href="/examples">Examples</a><a href="/search">Search</a></nav></details></div>
      <main id="main" class="portal-main"><nav class="breadcrumbs" aria-label="Breadcrumb"><a href="/">Home</a><span aria-hidden="true">/</span><span>Guides</span><span aria-hidden="true">/</span><span aria-current="page">Workspaces and gateway</span></nav><article class="documentation prose standalone"><span class="status status-beta">Preview guide · 0.8.1</span><h1>Workspaces and gateway</h1><p>A workspace runs isolated applications behind one domain-routing gateway. Add an application from the workspace root; the CLI scaffolds <code>apps/reports</code> and registers it in <code>wrnexus.workspace.ts</code>:</p><pre><code>wrnexus workspace add reports --domain=reports.localhost
bun install
bun run dev</code></pre><h2>Forward authentication</h2><p>Point protected applications at a dedicated verifier endpoint. The verifier must return 2xx for an authenticated session, 401/403 to deny access, or an HTTP redirect to begin browser login.</p><pre><code>// wrnexus.workspace.ts
&#123;
  name: "admin",
  dir: "apps/admin",
  domains: ["admin.localhost"],
  auth: &#123; forward: &#123; url: "http://sso.localhost:3000/api/verify" &#125; &#125;,
&#125;</code></pre><p>The gateway forwards cookies, authorization, original host, protocol, method, path, and query. Inside the verifier, <code>ctx.url</code> identifies the SSO verifier request—not the original admin URL. Use <code>@wrnexus/helpers</code> to reconstruct and validate the original destination:</p><pre><code>import type &#123; Context &#125; from "@wrnexus/core";
import &#123; redirectToLogin &#125; from "@wrnexus/helpers";

export const GET = async (ctx: Context) =&gt; &#123;
  if (await hasValidSession(ctx)) &#123;
    return new Response(null, &#123; status: 204 &#125;);
  &#125;

  return redirectToLogin(ctx, "/login", &#123;
    allowedHosts: ["admin.localhost:3000", "reports.localhost:3000"],
  &#125;);
&#125;;</code></pre><p>Always allowlist redirect hosts. After login, validate or sign the <code>returnTo</code> value before redirecting. Keep internal app ports private and open applications through the gateway port.</p><h2>Release scope</h2><p>This guide describes installed 0.8.1 capabilities. Follow linked package declarations for exact signatures; undocumented behavior is not guaranteed.</p><p><a href="/packages">Browse package APIs</a> · <a href="/guides/troubleshooting">Troubleshooting</a> · <a href="/support">Support</a></p></article></main>
      <footer><div class="footer-brand"><span class="footer-mark" aria-hidden="true">W</span><p><strong>WRNexusJS 0.8.1</strong><span>Server-first documentation for the Bun-native framework.</span></p></div><nav aria-label="Footer"><a href="/access">Request access</a><a href="/license">License</a><a href="/security">Security</a><a href="/support">Support</a><a href="/llms.txt">AI guide</a></nav><p class="footer-meta">Created by <a href="https://workroot.in/">WorkRoot</a> · Private Developer Preview</p></footer>
    </div>
  }
}