Apex and subdomains

ShowPony serves two surfaces from one app:

Host	Surface	Tenant
show-pony.localhost:4180 (apex)	Host login + dashboard	none (null)
demo.show-pony.localhost:4180	Public RSVP page	tenant key demo

Surface	Local	Cloud
Host login (apex)	http://show-pony.localhost:4180/login	https://show-pony.kumiko.rocks/login
Demo invite (rooftop)	http://demo.show-pony.localhost:4180/e/rooftop-launch	https://demo.show-pony.kumiko.rocks/e/rooftop-launch
Acme invite (offsite)	http://acme.show-pony.localhost:4180/e/acme-offsite	https://acme.show-pony.kumiko.rocks/e/acme-offsite

The host is decided by the subdomain a request arrives on, never by anything the guest sends. That is what makes a shared, anonymous app safe.

flowchart LR
  subgraph apex["apex : show-pony.localhost"]
    Landing[Marketing]
    Login[Login]
    Dash[Host dashboard]
  end
  subgraph demo["demo.show-pony.localhost"]
    Invite[Invite page]
    RSVP[Anonymous RSVP]
  end
  Guest((Guest)) --> Invite
  Invite --> RSVP
  Visitor((Visitor)) --> Landing
  Host((Host)) --> Login --> Dash

The same app process serves two HTML bundles. The server picks one by the Host header:

LightDark

LightDark

Strip the hostname

Port comes off the Host header first; then the subdomain suffix maps to tenant.key:

export function hostnameOf(host: string): string {
  const i = host.indexOf(":");
  return i === -1 ? host : host.slice(0, i);
}

// Apex / www: login, not a guest surface : no tenant.
if (host === baseDomain || host === `www.${baseDomain}`) return null;
// <key>.<baseDomain>: subdomain IS the tenant key.
if (host.endsWith(`.${baseDomain}`)) {
  return enabledTenantByKey(db, host.slice(0, -(baseDomain.length + 1)));
}

From src/tenant-routing.ts.

resolverTrust: "authoritative" is what actually closes this: a client-supplied X-Tenant header that disagrees with the hostname-resolved tenant is rejected with 400 tenant_mismatch before tenantExists ever runs. tenantExists alone only proves a real, enabled row, not that it matches the subdomain.

Wire at boot

bin/server.ts passes the anonymous-access helper into the dev server (subdomain resolver + SYSTEM tenant on the apex for /legal/*):

anonymousAccess: ({ db }) => createShowPonyAnonymousAccess({ db, baseDomain: BASE_DOMAIN }),

From bin/server.ts.

Production uses the same resolver shape in bin/main.ts with https origins.

Two bundles, routed by host

The apex serves static marketing pages (/, /de, /features, /pricing) and the admin SPA at /login (and authenticated app routes). Every subdomain serves index.html (public guest bundle). The server decides, rather than client-side hostname checks:

hostDispatch: (req) => {
  const host = hostnameOf(req.headers.get("host") ?? "");
  const path = new URL(req.url).pathname;
  if (host === BASE_DOMAIN || host === `www.${BASE_DOMAIN}`) {
    const dispatched = dispatchShowPonyApexStaticDev(path);
    if (dispatched !== null) return dispatched;
    return { kind: "html", entryName: "admin", injectSchema: true };
  }
  return { kind: "html", entryName: "public", injectSchema: false };
},

From bin/server.ts.

The complete file

// Host → tenant lookup for managed-pages `resolveApexTenant` (branding reads on the
// subdomain pages). The anonymous-request tenant itself comes from the FW host-routing
// feature, not from here.

import { normalizeHostname } from "@cosmicdrift/kumiko-bundled-features/host-routing";
import {
  isTenantServingPublicContent,
  type TenantLifecycleStatus,
  tenantTable,
} from "@cosmicdrift/kumiko-bundled-features/tenant";
import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";

type TenantRow = {
  id: TenantId;
  isEnabled: boolean;
  status: TenantLifecycleStatus;
};

// Module-global singleton, not per-stack state: acceptable because
// resolveApexTenant is wired once at static boot, never per request, and this process only
// ever runs one app stack. Bind BEFORE the first request that needs it
// (bindSubdomainPageResolver at boot) — a second stack in the same process would silently
// share this db.
let subdomainPageResolver: { db: DbConnection; baseDomain: string } | null = null;

/** Wire db for managed-pages `resolveApexTenant` (boot hook — wired once at static boot). */
export function bindSubdomainPageResolver(config: { db: DbConnection; baseDomain: string }): void {
  subdomainPageResolver = config;
}

/** Host → tenantId for managed-pages branding reads (subdomain = tenant.key). */
export async function resolveSubdomainPageTenant(host: string): Promise<TenantId | null> {
  if (!subdomainPageResolver) return null;
  const { db, baseDomain } = subdomainPageResolver;
  const hostname = normalizeHostname(host);
  if (hostname === null || !hostname.endsWith(`.${baseDomain}`)) return null;
  const key = hostname.slice(0, -(baseDomain.length + 1));
  if (key === "www") return null;
  const row = await fetchOne<TenantRow>(db, tenantTable, { key });
  return row !== undefined && isTenantServingPublicContent(row) ? row.id : null;
}

📄 On GitHub: src/tenant-routing.ts

Next: define the entities that flow through these two surfaces: chapter 5. For the marketing apex itself see chapter 12 and chapter 13.