feat(app-hosting): routing, wake gate and domains (ships dark)

.env.example

@@ -308,6 +308,33 @@ APNS_BUNDLE_ID=ai.pagespace.ios
 # FLY_MACHINES_ORG_TOKEN=your_fly_org_token_here
 # PUBLISHED_APPS_NETWORK=published-apps
 #
+# Serving tier (the router). PUBLISHED_APPS_APEX is REQUIRED once
+# APP_HOSTING_ENABLED=true — validateEnv() refuses to boot without it, on
+# purpose. Published apps run customer-authored SERVER code on subdomains of
+# this apex, so it must be a deliberate choice that has completed Public Suffix
+# List registration, never a value inherited from a default: without a PSL entry
+# one published app can set a cookie for the whole apex that every other
+# published app then sends. See ROUTING.md for the submission checklist, and note
+# that PSL listing is NOT retroactive — it ships inside browser releases.
+# APP_ROUTER_FLY_APP_NAME is the Fly app that terminates the apex and holds
+# custom-domain certs; it falls back to FLY_PROXY_APP_NAME and then to
+# 'pagespace-proxy', and it MUST have been created on PUBLISHED_APPS_NETWORK
+# because fly-replay cannot cross 6PN networks.
+# PUBLISHED_APPS_APEX=pagespace.app
+# APP_ROUTER_FLY_APP_NAME=pagespace-proxy
+#
+# Router secrets. BOTH must be >=32 characters when set, and both fail CLOSED:
+# unset (or below the floor) means the router refuses rather than skipping the
+# check. APP_ROUTER_PROXY_SECRET is what proves a request came from the edge
+# proxy — the route is mounted on the web app, which also answers at
+# pagespace.ai/api/..., so without it any internet caller could hand us a
+# published-app hostname and collect a fly-replay header, waking and billing any
+# app they can name. Set the SAME value as a secret on the proxy app.
+# APP_REPLAY_SECRET derives the per-app fly-replay `state` key.
+# Generate each with: openssl rand -hex 32
+# APP_REPLAY_SECRET=your_app_replay_secret_here_generate_with_openssl_rand_hex_32
+# APP_ROUTER_PROXY_SECRET=your_router_proxy_secret_here_generate_with_openssl_rand_hex_32
+#
 # Build & deploy pipeline (processor). APP_BUILD_SOURCE_ROOT is the directory
 # every build context is resolved UNDER — a source ref that escapes it is
 # refused — and leaving it unset means this processor is simply not a build

CHANGELOG.md

@@ -205,6 +205,19 @@ All notable user-facing changes to PageSpace are documented here. Format follows
 
 ### Fixed
 
+- **A custom domain stuck on SSL now tells you which DNS record to add** — when a certificate is
+  waiting on an ownership record, domain settings name it outright: the `_fly-ownership` TXT record,
+  where it goes, and every value that satisfies it — Fly accepts an app-scoped or an org-scoped
+  value, and whichever ones it offers are the ones you are shown. Previously that domain simply sat at "provisioning"
+  indefinitely with nothing to act on, because through the certificate's status alone "the
+  certificate has not issued yet" and "you were never told to add a DNS record" look identical — and
+  only one of them ever resolves on its own. The domain also stays healthy while it waits instead of
+  being marked failed, so a site already being served keeps serving. "Check SSL" now does more than
+  re-read a cached answer: once the record is visible in DNS it asks the certificate authority to
+  look again, rather than leaving you to wait out its own polling schedule. And removing a domain
+  now detaches its certificate, which previously kept billing after the domain was gone. Deleting an
+  entire drive does not yet do this, so remove its domains individually first if you want their
+  certificates released.
 - **An older AI conversation keeps its controls** — opening an AI page on a past conversation could
   drop the whole bar above the chat: no agent name, and no "+" to start a new conversation, so the
   only way to begin one was to go to the History tab and find the button there. Which of the two the

apps/web/src/__tests__/middleware.test.ts

@@ -31,8 +31,13 @@ vi.mock('@/middleware/security-headers', () => ({
   // Real predicate logic — middleware passes its result as `skipCSP` so the
   // handoff-bridge OAuth callbacks don't get a middleware CSP layered on top of
   // their own (see the isHandoffBridgeRoute describe block below).
-  isHandoffBridgeRoute: (pathname: string) =>
-    pathname === '/api/auth/google/callback' || pathname === '/api/auth/apple/callback',
+  // Real predicate logic, matching security-headers.ts: the handoff-bridge
+  // callbacks plus the published-app router all deliver their own CSP.
+  APP_ROUTER_ROUTE_PATH: '/api/app-hosting/router',
+  routeOwnsItsOwnCsp: (pathname: string) =>
+    pathname === '/api/auth/google/callback' ||
+    pathname === '/api/auth/apple/callback' ||
+    pathname === '/api/app-hosting/router',
   isPublicPageRoute: () => false,
   isPublishedSiteHost: () => false,
   isSecureRequest: () => true,
@@ -123,6 +128,99 @@ describe('middleware — /api/public/forms carve-outs', () => {
   });
 });
 
+// Regression coverage for a real bug found while building the published-app
+// routing tier: the router endpoint is called by pagespace-proxy with NO session
+// and no user — it authenticates via the APP_ROUTER_PROXY_SECRET shared secret
+// checked inside the route. Without a middleware carve-out, every such call is
+// 401'd before route.ts ever runs, which does not fail any handler test (those
+// invoke the route directly) but makes EVERY published app unreachable in a real
+// deployment. The route's own tests cannot see this; only this one can.
+describe('middleware — published-app router carve-out', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockGetSessionFromCookies.mockReturnValue(undefined);
+  });
+
+  it('skips the session-cookie check for a proxy call carrying no session', async () => {
+    mockValidateOriginForMiddleware.mockReturnValue({ valid: true, origin: null, skipped: true, reason: 'no origin' });
+    mockIsOriginValidationBlocking.mockReturnValue(true);
+
+    const request = buildRequest('/api/app-hosting/router');
+    const response = await middleware(request);
+
+    expect(response.status).not.toBe(401);
+    // createSecureResponse is mocked to always return 200, so the status alone
+    // would not catch the carve-out being removed — assert the session lookup
+    // was never reached.
+    expect(mockGetSessionFromCookies).not.toHaveBeenCalled();
+  });
+
+  it('lets the route own its CSP, so the parked page keeps its inline styles', async () => {
+    // The API CSP is `default-src 'none'`, which falls style-src back to 'none';
+    // browsers enforce the intersection of every delivered policy, so without
+    // the skip the customer-facing "app paused" page renders unstyled.
+    mockValidateOriginForMiddleware.mockReturnValue({ valid: true, origin: null, skipped: true, reason: 'no origin' });
+    mockIsOriginValidationBlocking.mockReturnValue(true);
+
+    await middleware(buildRequest('/api/app-hosting/router'));
+
+    expect(mockCreateSecureResponse).toHaveBeenCalledWith(
+      expect.anything(),
+      expect.anything(),
+      expect.objectContaining({ skipCSP: true }),
+    );
+  });
+
+  it('never runs origin validation — published apps have unbounded origins', async () => {
+    // A published app's own fetch carries its own origin, which is not and can
+    // never be in our allowlist. If origin validation ran here in blocking mode,
+    // every non-GET request a published app made to itself would 403.
+    mockValidateOriginForMiddleware.mockReturnValue({
+      valid: false,
+      origin: 'https://acme.pagespace.app',
+      skipped: false,
+      reason: 'origin not in allowlist',
+    });
+    mockIsOriginValidationBlocking.mockReturnValue(true);
+
+    const response = await middleware(
+      buildRequest('/api/app-hosting/router', { origin: 'https://acme.pagespace.app' }),
+    );
+
+    expect(response.status).not.toBe(403);
+    expect(mockValidateOriginForMiddleware).not.toHaveBeenCalled();
+  });
+
+  it('lets an OPTIONS preflight reach the route instead of answering it with our CORS policy', async () => {
+    // A preflight for a published app belongs to THAT app and must be replayed to
+    // it. The Bearer-API short-circuit would answer 204 with our own
+    // Access-Control-Allow-Headers, so a published app could never allow a custom
+    // request header on a cross-origin call.
+    mockValidateOriginForMiddleware.mockReturnValue({ valid: true, origin: null, skipped: true, reason: 'no origin' });
+    mockIsOriginValidationBlocking.mockReturnValue(true);
+
+    const response = await middleware(
+      buildRequest('/api/app-hosting/router', {}, 'OPTIONS'),
+    );
+
+    // The mocked createSecureResponse returns 200; the CORS short-circuit would
+    // have returned a 204 carrying Access-Control-Allow-Methods.
+    expect(response.headers.get('Access-Control-Allow-Methods')).toBeNull();
+    expect(response.status).not.toBe(204);
+  });
+
+  it('does not extend the carve-out to sibling app-hosting paths', async () => {
+    // Exact match only: a future authenticated /api/app-hosting/* route must not
+    // inherit an exemption meant for the one endpoint the proxy calls.
+    mockValidateOriginForMiddleware.mockReturnValue({ valid: true, origin: null, skipped: true, reason: 'no origin' });
+    mockIsOriginValidationBlocking.mockReturnValue(true);
+
+    await middleware(buildRequest('/api/app-hosting/apps'));
+
+    expect(mockGetSessionFromCookies).toHaveBeenCalled();
+  });
+});
+
 // Regression coverage for a real bug: middleware.ts used to hand-duplicate two
 // of the three bearer prefixes `@/lib/auth` actually authenticates (mcp_,
 // ps_sess_), silently missing ps_at_ (OAuth access tokens, `pagespace login`).

apps/web/src/app/api/__tests__/security-audit-coverage.test.ts

@@ -47,6 +47,7 @@ const AUDIT_EXEMPT_ROUTES = new Map<string, string>([
   ['internal/*', 'Internal service-to-service endpoints'],
   ['cron/scheduled-backups', 'HMAC-signed internal cron job — no user session, authenticated by shared secret, executes pre-authorized backup schedules'],
   ['memory/cron', 'Internal memory cron job'],
+  ['app-hosting/router', 'Published-app serving edge, called by pagespace-proxy on EVERY request to a published app (no fly-replay-cache on the metered tier, by design) — there is no user session to attribute, the caller is authenticated by the APP_ROUTER_PROXY_SECRET shared secret like the HMAC cron routes above, and one audit row per served asset would swamp the audit log with routing decisions. The security-relevant outcomes are counted at the edge instead: a refused caller answers 404 and a credit-exhausted app answers 402, both distinguishable in proxy logs.'],
   ['desktop-bridge/status', 'Desktop app connection status check'],
   ['provisioning-status/[slug]', 'Tenant provisioning status polling'],