From d4b645b1901b2ceb8177a734ca0998b007b2df98 Mon Sep 17 00:00:00 2001
From: Buck Doyle <buck.doyle@cardstack.com>
Date: Thu, 30 Jul 2026 10:39:42 -0500
Subject: [PATCH 01/12] Add redirect rules to host routing

A hostRoutingRules entry can now declare { path, redirectTo, statusCode? }
alongside the existing { path, instance } form. A matched redirect rule
answers 302 by default (301/308 opt-in); a realm-relative target resolves
against the realm's mount pathname while external http(s) URLs pass
through verbatim (other schemes are dropped). The request query string
carries over when the target has none, and the declared redirect fires
from either trailing-slash form in a single hop.

The SPA mirrors the server: an in-app transition to a redirect-ruled
path navigates to the target instead of rendering a card. The realm
config editor gains a card/redirect toggle with advisory validation of
the target.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/base/realm-config.gts                | 176 +++++++++++++++++-
 packages/host/app/routes/index.gts            |  17 +-
 .../host/app/services/host-mode-service.ts    |  32 +++-
 .../realm-config-routing-rule-edit-test.gts   |  65 +++++++
 packages/realm-server/handlers/serve-index.ts |  54 +++++-
 packages/realm-server/lib/realm-routing.ts    |  12 +-
 .../tests/host-routing-validation-test.ts     |  28 +++
 .../realm-server/tests/realm-routing-test.ts  |  28 ++-
 .../server-endpoints/index-responses-test.ts  | 100 +++++++++-
 .../runtime-common/host-routing-validation.ts | 103 +++++++++-
 packages/runtime-common/realm.ts              |  41 +++-
 .../tests/host-routing-validation-test.ts     |  82 ++++++++
 12 files changed, 699 insertions(+), 39 deletions(-)

diff --git a/packages/base/realm-config.gts b/packages/base/realm-config.gts
index 26e3abfbd69..4182bbc30a4 100644
--- a/packages/base/realm-config.gts
+++ b/packages/base/realm-config.gts
@@ -10,25 +10,34 @@ import {
   realmURL,
 } from './card-api';
 import BooleanField from './boolean';
+import NumberField from './number';
 import StringField from './string';
 import CardInfoTemplates from './default-templates/card-info';
 import {
   cardDefComputedFields,
+  DEFAULT_REDIRECT_STATUS,
   findDuplicateRoutingPaths,
   getField,
   getFieldIcon,
+  REDIRECT_STATUS_CODES,
+  validateRedirectTarget,
   validateRoutingPath,
 } from '@cardstack/runtime-common';
 import {
+  BoxelInput,
   BoxelInputGroup,
+  BoxelSelect,
   FieldContainer,
   Header,
+  RadioInput,
 } from '@cardstack/boxel-ui/components';
 import { eq } from '@cardstack/boxel-ui/helpers';
 import FileSettingsIcon from '@cardstack/boxel-icons/file-settings';
 import LinkIcon from '@cardstack/boxel-icons/link';
+import { fn } from '@ember/helper';
 import { action } from '@ember/object';
 import type Owner from '@ember/owner';
+import { tracked } from '@glimmer/tracking';
 import { startCase } from 'lodash-es';
 import type { FieldsTypeFor } from './card-api';
 
@@ -36,7 +45,12 @@ class RoutingRuleAtom extends Component<typeof RoutingRuleField> {
   <template>
     <span class='routing-rule-atom'>
       <span class='path'>{{if @model.path @model.path '(no path)'}}</span>
-      {{#if @model.instance}}
+      {{#if @model.redirectTo}}
+        <span class='arrow' aria-hidden='true'>→</span>
+        <span class='redirect-target' data-test-redirect-target>
+          {{@model.redirectTo}}
+        </span>
+      {{else if @model.instance}}
         <span class='arrow' aria-hidden='true'>→</span>
         <@fields.instance @format='atom' />
       {{/if}}
@@ -47,7 +61,8 @@ class RoutingRuleAtom extends Component<typeof RoutingRuleField> {
         align-items: center;
         gap: var(--boxel-sp-xxs);
       }
-      .path {
+      .path,
+      .redirect-target {
         font-family: var(--boxel-font-family-mono, monospace);
       }
       .arrow {
@@ -57,7 +72,25 @@ class RoutingRuleAtom extends Component<typeof RoutingRuleField> {
   </template>
 }
 
+let routingRuleKindGroupNumber = 0;
+
 class RoutingRuleEdit extends Component<typeof RoutingRuleField> {
+  // Which target editor is showing. Backed by the data: a rule whose
+  // `redirectTo` is non-null (empty string included — `setKind` seeds
+  // '' so the choice survives a reload) is a redirect rule. The tracked
+  // override exists only so the toggle responds instantly while the
+  // model write settles.
+  @tracked private kindOverride: 'card' | 'redirect' | null = null;
+
+  private kindItems: { id: 'card' | 'redirect'; text: string }[] = [
+    { id: 'card', text: 'Render a card' },
+    { id: 'redirect', text: 'Redirect' },
+  ];
+
+  private kindRadioGroup = `__routing_rule_kind${routingRuleKindGroupNumber++}__`;
+
+  private statusCodeOptions = [...REDIRECT_STATUS_CODES];
+
   constructor(owner: Owner, args: any) {
     super(owner, args);
     // The path input renders an empty input alongside a fixed `/`
@@ -104,6 +137,69 @@ class RoutingRuleEdit extends Component<typeof RoutingRuleField> {
     this.args.model.path = `/${trimmed}`;
   }
 
+  get kind(): 'card' | 'redirect' {
+    return (
+      this.kindOverride ??
+      (this.args.model.redirectTo != null ? 'redirect' : 'card')
+    );
+  }
+
+  get isRedirect(): boolean {
+    return this.kind === 'redirect';
+  }
+
+  // Switching kind clears the other kind's target so a rule is never
+  // ambiguous (the read path prefers `redirectTo` when both are set,
+  // but only a hand-edited realm.json can get into that state).
+  @action
+  setKind(kind: 'card' | 'redirect') {
+    this.kindOverride = kind;
+    if (kind === 'redirect') {
+      this.args.model.instance = undefined;
+      if (this.args.model.redirectTo == null) {
+        this.args.model.redirectTo = '';
+      }
+    } else {
+      this.args.model.redirectTo = undefined;
+      this.args.model.statusCode = undefined;
+    }
+  }
+
+  get redirectToValue(): string {
+    return this.args.model.redirectTo ?? '';
+  }
+
+  @action
+  setRedirectTo(value: string) {
+    this.args.model.redirectTo = value ?? '';
+  }
+
+  get redirectWarning(): string | undefined {
+    return validateRedirectTarget(this.args.model.redirectTo);
+  }
+
+  get selectedStatusCode(): number {
+    return this.args.model.statusCode ?? DEFAULT_REDIRECT_STATUS;
+  }
+
+  @action
+  setStatusCode(code: number) {
+    this.args.model.statusCode = code;
+  }
+
+  @action
+  statusCodeLabel(code: number): string {
+    switch (code) {
+      case 301:
+        return '301 · permanent';
+      case 308:
+        return '308 · permanent, method-preserving';
+      case 302:
+      default:
+        return '302 · temporary';
+    }
+  }
+
   // The chooser is locked to the consuming realm; pass it through
   // explicitly rather than letting LinksToEditor read it from
   // `RealmURLContext`. The context is only provided by the operator-mode
@@ -119,6 +215,21 @@ class RoutingRuleEdit extends Component<typeof RoutingRuleField> {
 
   <template>
     <div class='routing-rule-edit' data-test-routing-rule-edit>
+      <div class='kind-toggle' data-test-routing-rule-kind>
+        <RadioInput
+          @items={{this.kindItems}}
+          @groupDescription='Routing rule target'
+          name='{{this.kindRadioGroup}}'
+          @checkedId={{this.kind}}
+          @spacing='compact'
+          @hideBorder={{true}}
+          as |item|
+        >
+          <item.component @onChange={{fn this.setKind item.data.id}}>
+            {{item.data.text}}
+          </item.component>
+        </RadioInput>
+      </div>
       <div class='row'>
         <div class='path-cell'>
           <BoxelInputGroup
@@ -132,18 +243,45 @@ class RoutingRuleEdit extends Component<typeof RoutingRuleField> {
           </BoxelInputGroup>
         </div>
         <span class='arrow' aria-hidden='true'>→</span>
-        <div class='instance-cell'>
-          <@fields.instance
-            @lockConsumingRealm={{true}}
-            @consumingRealm={{this.consumingRealm}}
-          />
-        </div>
+        {{#if this.isRedirect}}
+          <div class='redirect-cell'>
+            <BoxelInput
+              @value={{this.redirectToValue}}
+              @onInput={{this.setRedirectTo}}
+              @placeholder='/path or https://example.com/page'
+              data-test-redirect-input
+            />
+            <div class='status-code-cell'>
+              <BoxelSelect
+                @options={{this.statusCodeOptions}}
+                @selected={{this.selectedStatusCode}}
+                @onChange={{this.setStatusCode}}
+                data-test-status-code-select
+                as |code|
+              >
+                {{this.statusCodeLabel code}}
+              </BoxelSelect>
+            </div>
+          </div>
+        {{else}}
+          <div class='instance-cell'>
+            <@fields.instance
+              @lockConsumingRealm={{true}}
+              @consumingRealm={{this.consumingRealm}}
+            />
+          </div>
+        {{/if}}
       </div>
       {{#if this.pathWarning}}
         <div class='path-warning' role='status' data-test-path-warning>
           {{this.pathWarning}}
         </div>
       {{/if}}
+      {{#if this.redirectWarning}}
+        <div class='path-warning' role='status' data-test-redirect-warning>
+          {{this.redirectWarning}}
+        </div>
+      {{/if}}
     </div>
     <style scoped>
       .routing-rule-edit {
@@ -182,6 +320,18 @@ class RoutingRuleEdit extends Component<typeof RoutingRuleField> {
       .instance-cell {
         min-width: 0;
       }
+      .redirect-cell {
+        display: grid;
+        grid-template-columns: 1fr auto;
+        gap: var(--boxel-sp-xs);
+        min-width: 0;
+      }
+      .redirect-cell :deep(input) {
+        font-family: var(--boxel-font-family-mono, monospace);
+      }
+      .status-code-cell {
+        min-width: 9rem;
+      }
       .path-warning {
         font-size: var(--boxel-font-size-xs);
         color: #92400e;
@@ -204,6 +354,16 @@ export class RoutingRuleField extends FieldDef {
       'Card instance to render when the realm is navigated at this path',
   });
 
+  @field redirectTo = contains(StringField, {
+    description:
+      'Redirect target — a path in this realm (e.g. "/terms") or an external http(s) URL. When set, the path redirects instead of rendering a card',
+  });
+
+  @field statusCode = contains(NumberField, {
+    description:
+      'HTTP status for a redirect rule: 301, 302 (the default), or 308',
+  });
+
   static atom = RoutingRuleAtom;
   static edit = RoutingRuleEdit;
 }
diff --git a/packages/host/app/routes/index.gts b/packages/host/app/routes/index.gts
index e9a618204b5..3c8ba4c28b6 100644
--- a/packages/host/app/routes/index.gts
+++ b/packages/host/app/routes/index.gts
@@ -85,14 +85,21 @@ export default class Card extends Route {
     if (this.hostModeService.isActive) {
       let normalizedPath = params.path ?? '';
       // CS-10055: a routing rule in the realm config can map a bare path
-      // to a target card. When the path matches a rule, use the rule's
-      // target id directly; otherwise resolve the path as a card URL
-      // under the host-mode origin.
-      let routedId = this.hostModeService.resolveRoutedPath(
+      // to a target card. When the path matches a serve rule, use the
+      // rule's target id directly; otherwise resolve the path as a card
+      // URL under the host-mode origin. A redirect rule is never
+      // rendered — navigate to its target instead, mirroring the 3xx
+      // the server answers for a full-page request to this path.
+      let routed = this.hostModeService.resolveRoutedPath(
         normalizedPath || '/',
       );
+      if (routed && 'redirectTo' in routed) {
+        this.hostModeService.redirectTo(routed.redirectTo);
+        return;
+      }
       let cardUrl =
-        routedId ?? `${this.hostModeService.hostModeOrigin}/${normalizedPath}`;
+        routed?.id ??
+        `${this.hostModeService.hostModeOrigin}/${normalizedPath}`;
 
       return this.store.get(cardUrl);
     }
diff --git a/packages/host/app/services/host-mode-service.ts b/packages/host/app/services/host-mode-service.ts
index bad049be283..e9911574669 100644
--- a/packages/host/app/services/host-mode-service.ts
+++ b/packages/host/app/services/host-mode-service.ts
@@ -35,6 +35,14 @@ interface PublishedRealmMetadata {
   currentCardUrlString: string | undefined;
 }
 
+// The host-scoped form of a routing rule as the realm-server injects it
+// into the config meta tag: every path (and any realm-relative redirect
+// target) is already prefixed with the realm's mount pathname, so a
+// redirect target can be handed straight to a location change.
+export type HostScopedRoutingRule =
+  | { path: string; id: string }
+  | { path: string; redirectTo: string; statusCode: number };
+
 export default class HostModeService extends Service {
   @service declare hostModeStateService: HostModeStateService;
   @service declare operatorModeStateService: OperatorModeStateService;
@@ -123,12 +131,15 @@ export default class HostModeService extends Service {
   // hostRoutingRules — so the first-render decision in the index route
   // is synchronous and the field is part of the typed config surface
   // rather than a window global.
-  get hostRoutingMap(): { path: string; id: string }[] {
+  get hostRoutingMap(): HostScopedRoutingRule[] {
     let map = (config as { hostRoutingMap?: unknown }).hostRoutingMap;
-    return Array.isArray(map) ? (map as { path: string; id: string }[]) : [];
+    return Array.isArray(map) ? (map as HostScopedRoutingRule[]) : [];
   }
 
-  // Returns the target card id if `path` matches a routing rule, else null.
+  // Returns the routing rule matching `path`, else null. A serve rule
+  // carries the target card `id` to render; a redirect rule carries the
+  // `redirectTo` target the SPA should navigate to instead of rendering
+  // anything (see `redirectTo` below).
   // `path` is the URL pathname on the host (what Ember's `/*path` catch-all
   // route delivers — e.g. `<user>/<realm>/whitepaper` for a request to
   // `https://host/<user>/<realm>/whitepaper`); a leading slash is added if
@@ -143,13 +154,24 @@ export default class HostModeService extends Service {
   // trailing slashes, preserves the root `/`) before comparing, so
   // `/realm` ↔ `/realm/` resolve and the client agrees with how the server
   // map builder and the editor normalize.
-  resolveRoutedPath(path: string): string | null {
+  resolveRoutedPath(path: string): HostScopedRoutingRule | null {
     let normalized = path.startsWith('/') ? path : `/${path}`;
     let canonical = normalizeRoutingPath(normalized);
     let rule = this.hostRoutingMap.find(
       (r) => normalizeRoutingPath(r.path) === canonical,
     );
-    return rule ? rule.id : null;
+    return rule ?? null;
+  }
+
+  // SPA-side counterpart of the server's HTTP redirect for a redirect
+  // routing rule: a full-page navigation to matched paths gets the 3xx
+  // from serve-index, but an in-app transition never leaves the SPA, so
+  // the index route calls this instead. `replace` mirrors an HTTP
+  // redirect, which leaves no history entry for the redirecting URL.
+  // Goes through ember-window-mock's `window` so tests can intercept the
+  // navigation.
+  redirectTo(target: string) {
+    window.location.replace(target);
   }
 
   get currentCardId() {
diff --git a/packages/host/tests/integration/components/realm-config-routing-rule-edit-test.gts b/packages/host/tests/integration/components/realm-config-routing-rule-edit-test.gts
index fbae2d51f37..7ce122c9c27 100644
--- a/packages/host/tests/integration/components/realm-config-routing-rule-edit-test.gts
+++ b/packages/host/tests/integration/components/realm-config-routing-rule-edit-test.gts
@@ -339,6 +339,71 @@ module(
       }
     });
 
+    test('a rule with a redirect target renders the redirect editor', async function (assert) {
+      await renderRealmConfigEdit([
+        { path: '/tos', redirectTo: '/terms', statusCode: 301 },
+      ]);
+
+      assert
+        .dom(
+          '[data-test-routing-rule-kind] [data-test-boxel-radio-option-id="redirect"] input[type="radio"]',
+        )
+        .isChecked('the kind toggle reflects the stored redirect');
+      assert
+        .dom('[data-test-redirect-input]')
+        .hasValue('/terms', 'the stored target is shown');
+      assert
+        .dom('[data-test-status-code-select]')
+        .containsText('301', 'the stored status code is selected');
+      assert
+        .dom('[data-test-add-new="instance"]')
+        .doesNotExist('the card chooser is not shown for a redirect rule');
+    });
+
+    test('switching a rule to a redirect swaps the target editor and validates the target', async function (assert) {
+      await renderRealmConfigEdit([{ path: '/docs' }]);
+
+      assert
+        .dom('[data-test-redirect-input]')
+        .doesNotExist('a card rule shows no redirect editor');
+
+      await click(
+        '[data-test-routing-rule-kind] [data-test-boxel-radio-option-id="redirect"] input[type="radio"]',
+      );
+      assert.dom('[data-test-redirect-input]').exists();
+      assert
+        .dom('[data-test-add-new="instance"]')
+        .doesNotExist('the card chooser is replaced by the redirect editor');
+
+      await fillIn('[data-test-redirect-input]', 'terms');
+      assert
+        .dom('[data-test-redirect-warning]')
+        .containsText(
+          'Redirect target must be a path starting with / or a full http(s) URL',
+          'a slash-less target warns',
+        );
+
+      await fillIn('[data-test-redirect-input]', 'https://example.com/terms');
+      assert
+        .dom('[data-test-redirect-warning]')
+        .doesNotExist('an external http(s) URL is allowed');
+
+      await fillIn('[data-test-redirect-input]', '/terms');
+      assert
+        .dom('[data-test-redirect-warning]')
+        .doesNotExist('a realm-relative path is allowed');
+
+      await click(
+        '[data-test-routing-rule-kind] [data-test-boxel-radio-option-id="card"] input[type="radio"]',
+      );
+      assert
+        .dom('[data-test-redirect-input]')
+        .doesNotExist('switching back to card removes the redirect editor');
+      assert
+        .dom('[data-test-add-new="instance"]')
+        .exists('switching back to card restores the chooser');
+    });
+
     test('typing into the path input always stores a leading slash', async function (assert) {
       await renderRealmConfigEdit([{}]);
 
diff --git a/packages/realm-server/handlers/serve-index.ts b/packages/realm-server/handlers/serve-index.ts
index 32b73899552..d8619988b41 100644
--- a/packages/realm-server/handlers/serve-index.ts
+++ b/packages/realm-server/handlers/serve-index.ts
@@ -1,9 +1,14 @@
 import type Koa from 'koa';
 import { JSDOM } from 'jsdom';
 import { merge } from 'lodash-es';
-import type { DBAdapter, Realm } from '@cardstack/runtime-common';
+import type {
+  DBAdapter,
+  HostRoutingRule,
+  Realm,
+} from '@cardstack/runtime-common';
 import {
   hasExtension,
+  isRedirectRoutingRule,
   logger,
   param,
   query,
@@ -387,13 +392,41 @@ export function createServeIndex(deps: ServeIndexDeps): ServeIndexHandlers {
     // a private routed path exists to an unauthenticated caller. The map is
     // also written into the @cardstack/host/config/environment meta tag
     // further down so the SPA can resolve the path post-hydration.
-    let routingMap: { path: string; id: string }[] = routedRealm
+    let routingMap: HostRoutingRule[] = routedRealm
       ? await routedRealm.getHostRoutingMap()
       : [];
     if (routingMap.length > 0) {
       // The match and its canonical form live once, in matchHostRoutingRule.
       let matched = await matchHostRoutingRule(requestURL, routingDeps);
       if (matched) {
+        if (isRedirectRoutingRule(matched.rule)) {
+          // A declared redirect rule. Redirect straight to the
+          // declared target from either trailing-slash form of the
+          // matched path — canonicalizing first would cost the client a
+          // second hop for no benefit. A realm-relative target resolves
+          // against the realm's mount pathname, mirroring how the
+          // rule's own `path` is mounted; extra leading slashes are
+          // collapsed so a target can never be read as protocol-
+          // relative. The request's query string carries over unless
+          // the target declares its own.
+          let { redirectTo, statusCode } = matched.rule;
+          let target: URL;
+          if (/^https?:/i.test(redirectTo)) {
+            target = new URL(redirectTo);
+          } else {
+            let realmPathname = new URL(matched.realm.url).pathname;
+            target = new URL(
+              realmPathname + redirectTo.replace(/^\/+/, ''),
+              requestURL,
+            );
+          }
+          if (requestURL.search && !target.search) {
+            target.search = requestURL.search;
+          }
+          ctxt.redirect(target.href);
+          ctxt.status = statusCode;
+          return;
+        }
         // Canonicalize the URL. A rule declared as '/pricing' matches both
         // '/pricing' and '/pricing/' (RealmPaths.local strips trailing
         // slashes); the canonical form is the realm mount pathname joined
@@ -517,10 +550,19 @@ export function createServeIndex(deps: ServeIndexDeps): ServeIndexHandlers {
       // the SPA's path lookup to be a direct equality match, prefix each
       // rule path with the realm's pathname before serializing.
       let realmPathname = new URL(routedRealm.url).pathname;
-      let hostScopedMap = routingMap.map((rule) => ({
-        path: realmPathname + rule.path.replace(/^\//, ''),
-        id: rule.id,
-      }));
+      let hostScopedMap = routingMap.map((rule) => {
+        let path = realmPathname + rule.path.replace(/^\//, '');
+        if (isRedirectRoutingRule(rule)) {
+          // A redirect rule's realm-relative target is prefixed the same
+          // way as its path, so the SPA can hand the value straight to a
+          // location change without knowing the realm's mount point.
+          let redirectTo = /^https?:/i.test(rule.redirectTo)
+            ? rule.redirectTo
+            : realmPathname + rule.redirectTo.replace(/^\/+/, '');
+          return { path, redirectTo, statusCode: rule.statusCode };
+        }
+        return { path, id: rule.id };
+      });
       // Per-request merge into the already-rewritten config meta tag.
       // The retrieveIndexHTML rewrite is cached process-wide because the
       // fields it touches are global; the routing map is per-realm so it
diff --git a/packages/realm-server/lib/realm-routing.ts b/packages/realm-server/lib/realm-routing.ts
index 90f6bb54e33..90cf652012a 100644
--- a/packages/realm-server/lib/realm-routing.ts
+++ b/packages/realm-server/lib/realm-routing.ts
@@ -1,7 +1,11 @@
 import { join } from 'path';
 import fsExtra from 'fs-extra';
 const { existsSync } = fsExtra;
-import type { DBAdapter, Realm } from '@cardstack/runtime-common';
+import type {
+  DBAdapter,
+  HostRoutingRule,
+  Realm,
+} from '@cardstack/runtime-common';
 import {
   executableExtensions,
   fetchRealmPermissions,
@@ -99,10 +103,12 @@ export async function findOrMountRealm(
 // under: the realm mount pathname joined with the rule's declared path
 // (so the realm-root rule '/' keeps its trailing slash, while a sub-path
 // rule like '/pricing' has none). Callers redirect to it when the request
-// arrived under a different form.
+// arrived under a different form. The rule is the serve/redirect union
+// from the realm's routing map — a redirect rule is never served, so its
+// canonicalPathname is only meaningful for serve rules.
 export type MatchedHostRoutingRule = {
   realm: Realm;
-  rule: { path: string; id: string };
+  rule: HostRoutingRule;
   canonicalPathname: string;
 };
 
diff --git a/packages/realm-server/tests/host-routing-validation-test.ts b/packages/realm-server/tests/host-routing-validation-test.ts
index e0bc21d76a3..0651f840fdb 100644
--- a/packages/realm-server/tests/host-routing-validation-test.ts
+++ b/packages/realm-server/tests/host-routing-validation-test.ts
@@ -70,4 +70,32 @@ module(basename(import.meta.filename), function () {
       await runSharedTest(hostRoutingValidationTests, assert, {});
     });
   });
+
+  module('validateRedirectTarget', function () {
+    test('validateRedirectTarget: no warning for empty or unset targets', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+
+    test('validateRedirectTarget: accepts realm-relative paths, including query strings', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+
+    test('validateRedirectTarget: accepts external http(s) URLs', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+
+    test('validateRedirectTarget: warns on non-http(s) schemes', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+
+    test('validateRedirectTarget: warns on slash-less and protocol-relative targets', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+  });
+
+  module('parseRedirectStatusCode', function () {
+    test('parseRedirectStatusCode: coerces supported codes, rejects everything else', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+  });
 });
diff --git a/packages/realm-server/tests/realm-routing-test.ts b/packages/realm-server/tests/realm-routing-test.ts
index 9403e54b368..ffecee77c9e 100644
--- a/packages/realm-server/tests/realm-routing-test.ts
+++ b/packages/realm-server/tests/realm-routing-test.ts
@@ -15,7 +15,11 @@ import { resolveRealmsForFederatedRequest } from '../lib/realm-routing.ts';
 // a relative reference (the recommended form, portable across realm URL
 // changes), one is cross-realm — dropped by the same-realm guard — and
 // one is authored with a trailing slash, which must be normalized to its
-// slash-free form so it matches request paths.
+// slash-free form so it matches request paths. The redirect rules
+// cover: a realm-relative target with the default status, an external
+// target with an explicit status, an invalid (non-http) target —
+// dropped — and a rule carrying both a redirect and an instance, where
+// the redirect wins.
 function makeRoutingFixture(): Record<
   string,
   string | LooseSingleCardDocument
@@ -53,6 +57,14 @@ function makeRoutingFixture(): Record<
             { path: '/rel' },
             { path: '/foreign' },
             { path: '/trailing/' },
+            { path: '/tos', redirectTo: '/terms' },
+            {
+              path: '/blog',
+              redirectTo: 'https://blog.example.com/',
+              statusCode: 301,
+            },
+            { path: '/bad-redirect', redirectTo: 'javascript:alert(1)' },
+            { path: '/ambiguous', redirectTo: '/elsewhere' },
           ],
         },
         relationships: {
@@ -72,6 +84,11 @@ function makeRoutingFixture(): Record<
           'hostRoutingRules.2.instance': {
             links: { self: './white-paper' },
           },
+          // Carries BOTH a redirect and an instance (only reachable by
+          // hand-editing realm.json): the redirect must win.
+          'hostRoutingRules.6.instance': {
+            links: { self: './white-paper' },
+          },
         },
         meta: {
           adoptsFrom: {
@@ -110,8 +127,15 @@ module(basename(import.meta.filename), function () {
         [
           { path: '/rel', id: `${realmURL.href}white-paper` },
           { path: '/trailing', id: `${realmURL.href}white-paper` },
+          { path: '/tos', redirectTo: '/terms', statusCode: 302 },
+          {
+            path: '/blog',
+            redirectTo: 'https://blog.example.com/',
+            statusCode: 301,
+          },
+          { path: '/ambiguous', redirectTo: '/elsewhere', statusCode: 302 },
         ],
-        'relative reference resolved against the realm root; cross-realm rule filtered; trailing-slash rule normalized to /trailing',
+        'relative reference resolved against the realm root; cross-realm rule filtered; trailing-slash rule normalized to /trailing; redirect rules surface with their (default) status; the invalid javascript: target is dropped; a rule with both targets resolves as a redirect',
       );
     });
 
diff --git a/packages/realm-server/tests/server-endpoints/index-responses-test.ts b/packages/realm-server/tests/server-endpoints/index-responses-test.ts
index 6d1b76e3a20..2d5efd91f1a 100644
--- a/packages/realm-server/tests/server-endpoints/index-responses-test.ts
+++ b/packages/realm-server/tests/server-endpoints/index-responses-test.ts
@@ -1743,7 +1743,19 @@ module(`server-endpoints/${basename(import.meta.filename)}`, function () {
                   type: 'card',
                   attributes: {
                     cardInfo: { name: 'Routing Source Realm' },
-                    hostRoutingRules: [{ path: '/' }, { path: '/pricing' }],
+                    hostRoutingRules: [
+                      { path: '/' },
+                      { path: '/pricing' },
+                      // Redirect rules: a realm-relative target using
+                      // the default status code, and an external
+                      // target with an explicit permanent code.
+                      { path: '/tos', redirectTo: '/terms' },
+                      {
+                        path: '/external',
+                        redirectTo: 'https://example.com/landing',
+                        statusCode: 301,
+                      },
+                    ],
                   },
                   relationships: {
                     'hostRoutingRules.0.instance': {
@@ -1871,6 +1883,92 @@ module(`server-endpoints/${basename(import.meta.filename)}`, function () {
         );
       });
 
+      test('a redirect rule with a realm-relative target answers the default 302, resolved against the realm mount', async function (assert) {
+        let response = await request
+          .get(`${publishedRealmPath}tos`)
+          .set('Host', publishedRealmHost)
+          .set('Accept', 'text/html');
+
+        assert.strictEqual(
+          response.status,
+          302,
+          'redirect rule answers its (default) status code',
+        );
+        assert.strictEqual(
+          response.headers['location'],
+          `http://${publishedRealmHost}${publishedRealmPath}terms`,
+          'relative target resolves against the realm mount pathname',
+        );
+      });
+
+      test('a redirect rule fires from the trailing-slash form in one hop', async function (assert) {
+        let response = await request
+          .get(`${publishedRealmPath}tos/`)
+          .set('Host', publishedRealmHost)
+          .set('Accept', 'text/html');
+
+        // The declared redirect wins over trailing-slash canonicalization —
+        // a 308 to /tos first would cost the client a second round-trip.
+        assert.strictEqual(
+          response.status,
+          302,
+          'trailing-slash form redirects straight to the target, not via a canonicalizing 308',
+        );
+        assert.strictEqual(
+          response.headers['location'],
+          `http://${publishedRealmHost}${publishedRealmPath}terms`,
+          'same target as the bare form',
+        );
+      });
+
+      test('a redirect rule carries the request query string over to a target without its own', async function (assert) {
+        let response = await request
+          .get(`${publishedRealmPath}tos?utm_source=newsletter`)
+          .set('Host', publishedRealmHost)
+          .set('Accept', 'text/html');
+
+        assert.strictEqual(response.status, 302);
+        assert.strictEqual(
+          response.headers['location'],
+          `http://${publishedRealmHost}${publishedRealmPath}terms?utm_source=newsletter`,
+          'query string is preserved on the redirect target',
+        );
+      });
+
+      test('a redirect rule may target an external URL with an explicit status code', async function (assert) {
+        let response = await request
+          .get(`${publishedRealmPath}external`)
+          .set('Host', publishedRealmHost)
+          .set('Accept', '*/*');
+
+        assert.strictEqual(
+          response.status,
+          301,
+          'the authored status code is used',
+        );
+        assert.strictEqual(
+          response.headers['location'],
+          'https://example.com/landing',
+          'external target is emitted verbatim',
+        );
+      });
+
+      test('redirect rules are injected into the host config routing map', async function (assert) {
+        let response = await request
+          .get(`${publishedRealmPath}pricing`)
+          .set('Host', publishedRealmHost)
+          .set('Accept', 'text/html');
+
+        assert.strictEqual(response.status, 200);
+        // The routing map rides the URL-encoded config meta tag; letters
+        // are not percent-encoded, so the discriminant field name is
+        // directly visible in the served HTML.
+        assert.true(
+          response.text.includes('redirectTo'),
+          'the injected hostRoutingMap carries the redirect rules',
+        );
+      });
+
       test('a non-public realm does not disclose routes via a canonical redirect', async function (assert) {
         // Drop the published realm's permissions so it is no longer publicly
         // readable. `fetchRealmPermissions` reads this table uncached, so the
diff --git a/packages/runtime-common/host-routing-validation.ts b/packages/runtime-common/host-routing-validation.ts
index 41d8d255c4e..39544d57e97 100644
--- a/packages/runtime-common/host-routing-validation.ts
+++ b/packages/runtime-common/host-routing-validation.ts
@@ -1,10 +1,40 @@
-// Advisory validators for the host routing rule editor. These do not
-// reject input — they produce a human-readable warning the UI shows
-// next to the offending rule. Server-side enforcement is intentionally
-// out of scope for the MVP.
+// Shared vocabulary for host routing rules: the rule union type the
+// resolved routing map is made of, plus advisory validators for the
+// rule editor. The validators do not reject input — they produce a
+// human-readable warning the UI shows next to the offending rule.
+// Server-side enforcement lives in `Realm.getHostRoutingMap`, which
+// drops rules the validators here would warn about.
 
 const VALID_PATH_PATTERN = /^\/(?:[A-Za-z0-9._~/-]|%[0-9A-Fa-f]{2})*$/;
 
+export const REDIRECT_STATUS_CODES = [301, 302, 308] as const;
+export type RedirectStatusCode = (typeof REDIRECT_STATUS_CODES)[number];
+
+// Temporary (302) is the safe default: a realm config is hand-editable
+// and iterated on, and the permanent codes (301/308) are cached by
+// browsers with no practical way to roll back once a visitor has seen
+// one. Authors opt into permanence explicitly via `statusCode`.
+export const DEFAULT_REDIRECT_STATUS: RedirectStatusCode = 302;
+
+// A resolved routing rule maps a path within the realm either to a card
+// to render at that path, or to a redirect target. `redirectTo` is
+// either a realm-relative path ('/terms', resolved against the realm's
+// mount pathname just like `path` is) or an absolute http(s) URL —
+// external targets are allowed.
+export type HostRoutingServeRule = { path: string; id: string };
+export type HostRoutingRedirectRule = {
+  path: string;
+  redirectTo: string;
+  statusCode: RedirectStatusCode;
+};
+export type HostRoutingRule = HostRoutingServeRule | HostRoutingRedirectRule;
+
+export function isRedirectRoutingRule(
+  rule: HostRoutingRule,
+): rule is HostRoutingRedirectRule {
+  return 'redirectTo' in rule;
+}
+
 /**
  * Canonical form of a routing rule path: a trailing slash is stripped so
  * `/pricing/` and `/pricing` compare and match identically, with the realm
@@ -60,6 +90,71 @@ export function validateRoutingPath(
   return undefined;
 }
 
+const ABSOLUTE_URL_PATTERN = /^[A-Za-z][A-Za-z0-9+.-]*:/;
+
+/**
+ * Returns a warning message for a redirect target that is non-empty but
+ * malformed; empty / whitespace-only / null / undefined input returns
+ * `undefined` so an in-progress rule never shows the warning.
+ *
+ * Accepted forms:
+ * - A realm-relative path starting with a single `/` (resolved against
+ *   the realm's mount pathname, like a rule's `path`). Unlike `path`,
+ *   the character set is not restricted — a target may carry a query
+ *   string.
+ * - An absolute `http:`/`https:` URL; external hosts are allowed. Other
+ *   schemes (`javascript:`, `data:`, …) are rejected.
+ *
+ * A protocol-relative target (`//example.com/x`) warns rather than
+ * silently becoming the realm path `/example.com/x` (extra leading
+ * slashes are collapsed when the redirect resolves).
+ */
+export function validateRedirectTarget(
+  target: string | null | undefined,
+): string | undefined {
+  if (target == null) return undefined;
+  let trimmed = target.trim();
+  if (!trimmed) return undefined;
+  if (ABSOLUTE_URL_PATTERN.test(trimmed)) {
+    let parsed: URL | undefined;
+    try {
+      parsed = new URL(trimmed);
+    } catch {
+      parsed = undefined;
+    }
+    if (
+      !parsed ||
+      (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+    ) {
+      return 'Redirect target must be a path starting with / or a full http(s) URL';
+    }
+    return undefined;
+  }
+  if (!trimmed.startsWith('/')) {
+    return 'Redirect target must be a path starting with / or a full http(s) URL';
+  }
+  if (trimmed.startsWith('//')) {
+    return 'Redirect target must start with a single /; use a full http(s) URL for an external target';
+  }
+  return undefined;
+}
+
+/**
+ * Coerces an authored `statusCode` value to one of the supported
+ * redirect codes. Accepts a number or a numeric string; anything else
+ * (including unsupported codes like 307) returns `undefined` so the
+ * caller can fall back to `DEFAULT_REDIRECT_STATUS`.
+ */
+export function parseRedirectStatusCode(
+  value: unknown,
+): RedirectStatusCode | undefined {
+  let candidate =
+    typeof value === 'string' && value.trim() !== '' ? Number(value) : value;
+  return (REDIRECT_STATUS_CODES as readonly unknown[]).includes(candidate)
+    ? (candidate as RedirectStatusCode)
+    : undefined;
+}
+
 /**
  * Returns the set of non-empty paths that appear on more than one
  * routing rule, in insertion order. Empty paths are ignored — they
diff --git a/packages/runtime-common/realm.ts b/packages/runtime-common/realm.ts
index 21159781068..0bad0f20619 100644
--- a/packages/runtime-common/realm.ts
+++ b/packages/runtime-common/realm.ts
@@ -48,7 +48,13 @@ import {
   HtmlResourceType,
 } from './resource-types.ts';
 import { normalizeRelationships } from './relationship-utils.ts';
-import { normalizeRoutingPath } from './host-routing-validation.ts';
+import {
+  DEFAULT_REDIRECT_STATUS,
+  normalizeRoutingPath,
+  parseRedirectStatusCode,
+  validateRedirectTarget,
+  type HostRoutingRule,
+} from './host-routing-validation.ts';
 import type { LocalPath } from './paths.ts';
 import { RealmPaths, ensureTrailingSlash, join } from './paths.ts';
 import type ms from 'ms';
@@ -886,7 +892,7 @@ export class Realm {
   // every index swap (full/incremental/publish) both locally and on peer
   // replicas via the realm_index_updated broadcast. `null` means "not yet
   // computed"; an empty array is a valid cached result (no routing rules).
-  #cachedHostRoutingMap: { path: string; id: string }[] | null = null;
+  #cachedHostRoutingMap: HostRoutingRule[] | null = null;
 
   // This loader is not meant to be used operationally, rather it serves as a
   // template that we clone for each indexing operation
@@ -6833,8 +6839,10 @@ export class Realm {
   // The `instance` field is `linksTo(CardDef)`, so the indexed
   // searchDoc flattens each rule's link as `{ id, ...flattened
   // linked-card attrs }`. We only need the absolute `id` here.
-  // Returns absolute URLs.
-  async getHostRoutingMap(): Promise<{ path: string; id: string }[]> {
+  // Returns absolute URLs. A rule may instead declare a redirect
+  // (`redirectTo` + optional `statusCode`); those surface as redirect
+  // entries in the map.
+  async getHostRoutingMap(): Promise<HostRoutingRule[]> {
     if (this.#cachedHostRoutingMap) {
       return this.#cachedHostRoutingMap;
     }
@@ -6851,7 +6859,7 @@ export class Realm {
       if (!Array.isArray(rules)) {
         return (this.#cachedHostRoutingMap = []);
       }
-      let map = rules.flatMap((rule) => {
+      let map = rules.flatMap((rule): HostRoutingRule[] => {
         if (!rule || typeof rule !== 'object') return [];
         let path = (rule as Record<string, unknown>).path;
         let instance = (rule as Record<string, unknown>).instance;
@@ -6865,6 +6873,29 @@ export class Realm {
         // the editor's duplicate detection so a '/pricing' + '/pricing/'
         // collision is flagged there. The realm-root rule '/' is preserved.
         let normalizedPath = normalizeRoutingPath(path);
+        let redirectTo = (rule as Record<string, unknown>).redirectTo;
+        if (typeof redirectTo === 'string' && redirectTo.trim()) {
+          // A redirect rule. When a rule carries both `redirectTo` and
+          // `instance` (only possible by hand-editing realm.json — the
+          // editor clears one when the other is chosen), the redirect
+          // wins: it is the more explicit declaration, and silently
+          // dropping the rule would dead-end the path.
+          let target = redirectTo.trim();
+          let warning = validateRedirectTarget(target);
+          if (warning) {
+            this.#log.warn(
+              `dropping host routing rule for path "${normalizedPath}" — invalid redirect target ${JSON.stringify(
+                target,
+              )}: ${warning}`,
+            );
+            return [];
+          }
+          let statusCode =
+            parseRedirectStatusCode(
+              (rule as Record<string, unknown>).statusCode,
+            ) ?? DEFAULT_REDIRECT_STATUS;
+          return [{ path: normalizedPath, redirectTo: target, statusCode }];
+        }
         if (!instance || typeof instance !== 'object') return [];
         let id = (instance as Record<string, unknown>).id;
         if (typeof id !== 'string') return [];
diff --git a/packages/runtime-common/tests/host-routing-validation-test.ts b/packages/runtime-common/tests/host-routing-validation-test.ts
index 9f338a8cb7b..76f826302a1 100644
--- a/packages/runtime-common/tests/host-routing-validation-test.ts
+++ b/packages/runtime-common/tests/host-routing-validation-test.ts
@@ -1,6 +1,8 @@
 import {
   findDuplicateRoutingPaths,
   normalizeRoutingPath,
+  parseRedirectStatusCode,
+  validateRedirectTarget,
   validateRoutingPath,
 } from '../host-routing-validation.ts';
 import type { SharedTests } from '../helpers/index.ts';
@@ -8,6 +10,10 @@ import type { SharedTests } from '../helpers/index.ts';
 const INVALID_CHARS_MSG =
   'Path may only contain letters, numbers, /, -, _, ., ~, or %XX-encoded characters';
 const MISSING_SLASH_MSG = 'Path must start with /';
+const INVALID_TARGET_MSG =
+  'Redirect target must be a path starting with / or a full http(s) URL';
+const PROTOCOL_RELATIVE_MSG =
+  'Redirect target must start with a single /; use a full http(s) URL for an external target';
 
 const tests: SharedTests<unknown> = Object.freeze({
   'validateRoutingPath: no warning for empty or whitespace paths': async (
@@ -191,6 +197,82 @@ const tests: SharedTests<unknown> = Object.freeze({
       assert.strictEqual(normalizeRoutingPath('/'), '/');
       assert.strictEqual(normalizeRoutingPath('//'), '/');
     },
+
+  'validateRedirectTarget: no warning for empty or unset targets': async (
+    assert,
+  ) => {
+    assert.strictEqual(validateRedirectTarget(null), undefined);
+    assert.strictEqual(validateRedirectTarget(undefined), undefined);
+    assert.strictEqual(validateRedirectTarget(''), undefined);
+    assert.strictEqual(validateRedirectTarget('   '), undefined);
+  },
+
+  'validateRedirectTarget: accepts realm-relative paths, including query strings':
+    async (assert) => {
+      assert.strictEqual(validateRedirectTarget('/terms'), undefined);
+      assert.strictEqual(validateRedirectTarget('/blog/2024/post'), undefined);
+      assert.strictEqual(validateRedirectTarget('/terms?ref=tos'), undefined);
+      assert.strictEqual(validateRedirectTarget('  /terms  '), undefined);
+      assert.strictEqual(validateRedirectTarget('/'), undefined);
+    },
+
+  'validateRedirectTarget: accepts external http(s) URLs': async (assert) => {
+    assert.strictEqual(
+      validateRedirectTarget('https://example.com/page'),
+      undefined,
+    );
+    assert.strictEqual(validateRedirectTarget('http://example.com'), undefined);
+    assert.strictEqual(
+      validateRedirectTarget('https://example.com/page?x=1#frag'),
+      undefined,
+    );
+  },
+
+  'validateRedirectTarget: warns on non-http(s) schemes': async (assert) => {
+    assert.strictEqual(
+      validateRedirectTarget('javascript:alert(1)'),
+      INVALID_TARGET_MSG,
+    );
+    assert.strictEqual(
+      validateRedirectTarget('data:text/html,hi'),
+      INVALID_TARGET_MSG,
+    );
+    assert.strictEqual(
+      validateRedirectTarget('mailto:someone@example.com'),
+      INVALID_TARGET_MSG,
+    );
+  },
+
+  'validateRedirectTarget: warns on slash-less and protocol-relative targets':
+    async (assert) => {
+      assert.strictEqual(validateRedirectTarget('terms'), INVALID_TARGET_MSG);
+      assert.strictEqual(
+        validateRedirectTarget('example.com/terms'),
+        INVALID_TARGET_MSG,
+      );
+      // '//example.com/x' would otherwise resolve as the realm path
+      // '/example.com/x' (leading slashes collapse), which is unlikely to
+      // be what the author meant — steer them to a full URL.
+      assert.strictEqual(
+        validateRedirectTarget('//example.com/x'),
+        PROTOCOL_RELATIVE_MSG,
+      );
+    },
+
+  'parseRedirectStatusCode: coerces supported codes, rejects everything else':
+    async (assert) => {
+      assert.strictEqual(parseRedirectStatusCode(301), 301);
+      assert.strictEqual(parseRedirectStatusCode(302), 302);
+      assert.strictEqual(parseRedirectStatusCode(308), 308);
+      assert.strictEqual(parseRedirectStatusCode('301'), 301);
+      assert.strictEqual(parseRedirectStatusCode(' 308 '), 308);
+      assert.strictEqual(parseRedirectStatusCode(307), undefined);
+      assert.strictEqual(parseRedirectStatusCode(200), undefined);
+      assert.strictEqual(parseRedirectStatusCode('perm'), undefined);
+      assert.strictEqual(parseRedirectStatusCode(''), undefined);
+      assert.strictEqual(parseRedirectStatusCode(null), undefined);
+      assert.strictEqual(parseRedirectStatusCode(undefined), undefined);
+    },
 });
 
 export default tests;

From c45e1cb070218339854af041c1822593fcab215c Mon Sep 17 00:00:00 2001
From: Buck Doyle <buck.doyle@cardstack.com>
Date: Fri, 31 Jul 2026 14:00:08 -0500
Subject: [PATCH 02/12] Stack the redirect status picker below the target input
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Side by side, the URL input's and the select's combined minimum width
overflows the rule container at operator-mode stack width — the select
escaped past the container edge. Stacking them lets the 1fr track
shrink the input instead.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/base/realm-config.gts | 12 ++++++++++--
 1 file changed, 10 insertions(+), 2 deletions(-)

diff --git a/packages/base/realm-config.gts b/packages/base/realm-config.gts
index 4182bbc30a4..314f522924c 100644
--- a/packages/base/realm-config.gts
+++ b/packages/base/realm-config.gts
@@ -320,17 +320,25 @@ class RoutingRuleEdit extends Component<typeof RoutingRuleField> {
       .instance-cell {
         min-width: 0;
       }
+      /* The target cell shares a 1fr track with the path input and the
+         card can render quite narrow (operator-mode stack item), so the
+         status picker stacks BELOW the target input rather than beside
+         it — side-by-side, their combined minimum width overflows the
+         rule container. min-width: 0 (cell and input) lets the track
+         shrink the URL input instead of pushing the row wider. */
       .redirect-cell {
         display: grid;
-        grid-template-columns: 1fr auto;
-        gap: var(--boxel-sp-xs);
+        gap: var(--boxel-sp-xxs);
         min-width: 0;
       }
       .redirect-cell :deep(input) {
         font-family: var(--boxel-font-family-mono, monospace);
+        min-width: 0;
       }
       .status-code-cell {
+        justify-self: start;
         min-width: 9rem;
+        max-width: 100%;
       }
       .path-warning {
         font-size: var(--boxel-font-size-xs);

From d3d532cec912b27a3ec0fcb07529389f52ea2a1b Mon Sep 17 00:00:00 2001
From: Buck Doyle <buck.doyle@cardstack.com>
Date: Fri, 31 Jul 2026 14:11:30 -0500
Subject: [PATCH 03/12] Drop 308 from redirect rule status codes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Routed paths only ever serve GET/HEAD page requests — card mutations go
through the JSON API on different URLs — so the method-preserving 308
behaves identically to 301 here and just clutters the choice. Redirect
rules now offer 301 or 302 (the default). The trailing-slash
canonicalization redirect keeps its 308; it is not author-configurable.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/base/realm-config.gts                   | 12 ++----------
 .../runtime-common/host-routing-validation.ts    | 16 ++++++++++------
 .../tests/host-routing-validation-test.ts        |  7 +++++--
 3 files changed, 17 insertions(+), 18 deletions(-)

diff --git a/packages/base/realm-config.gts b/packages/base/realm-config.gts
index 314f522924c..a645114f9a9 100644
--- a/packages/base/realm-config.gts
+++ b/packages/base/realm-config.gts
@@ -189,15 +189,7 @@ class RoutingRuleEdit extends Component<typeof RoutingRuleField> {
 
   @action
   statusCodeLabel(code: number): string {
-    switch (code) {
-      case 301:
-        return '301 · permanent';
-      case 308:
-        return '308 · permanent, method-preserving';
-      case 302:
-      default:
-        return '302 · temporary';
-    }
+    return code === 301 ? '301 · permanent' : '302 · temporary';
   }
 
   // The chooser is locked to the consuming realm; pass it through
@@ -369,7 +361,7 @@ export class RoutingRuleField extends FieldDef {
 
   @field statusCode = contains(NumberField, {
     description:
-      'HTTP status for a redirect rule: 301, 302 (the default), or 308',
+      'HTTP status for a redirect rule: 301 (permanent) or 302 (temporary, the default)',
   });
 
   static atom = RoutingRuleAtom;
diff --git a/packages/runtime-common/host-routing-validation.ts b/packages/runtime-common/host-routing-validation.ts
index 39544d57e97..a9205c1e809 100644
--- a/packages/runtime-common/host-routing-validation.ts
+++ b/packages/runtime-common/host-routing-validation.ts
@@ -7,13 +7,17 @@
 
 const VALID_PATH_PATTERN = /^\/(?:[A-Za-z0-9._~/-]|%[0-9A-Fa-f]{2})*$/;
 
-export const REDIRECT_STATUS_CODES = [301, 302, 308] as const;
+// Only 301/302 are offered: routed paths serve GET/HEAD page requests
+// exclusively (card mutations live on the JSON API, not these URLs), so
+// the method-preserving codes (307/308) would behave identically to
+// their plain counterparts and just clutter the choice.
+export const REDIRECT_STATUS_CODES = [301, 302] as const;
 export type RedirectStatusCode = (typeof REDIRECT_STATUS_CODES)[number];
 
 // Temporary (302) is the safe default: a realm config is hand-editable
-// and iterated on, and the permanent codes (301/308) are cached by
-// browsers with no practical way to roll back once a visitor has seen
-// one. Authors opt into permanence explicitly via `statusCode`.
+// and iterated on, and a permanent 301 is cached by browsers with no
+// practical way to roll back once a visitor has seen it. Authors opt
+// into permanence explicitly via `statusCode`.
 export const DEFAULT_REDIRECT_STATUS: RedirectStatusCode = 302;
 
 // A resolved routing rule maps a path within the realm either to a card
@@ -142,8 +146,8 @@ export function validateRedirectTarget(
 /**
  * Coerces an authored `statusCode` value to one of the supported
  * redirect codes. Accepts a number or a numeric string; anything else
- * (including unsupported codes like 307) returns `undefined` so the
- * caller can fall back to `DEFAULT_REDIRECT_STATUS`.
+ * (including unsupported codes like 307 or 308) returns `undefined` so
+ * the caller can fall back to `DEFAULT_REDIRECT_STATUS`.
  */
 export function parseRedirectStatusCode(
   value: unknown,
diff --git a/packages/runtime-common/tests/host-routing-validation-test.ts b/packages/runtime-common/tests/host-routing-validation-test.ts
index 76f826302a1..58c8679b421 100644
--- a/packages/runtime-common/tests/host-routing-validation-test.ts
+++ b/packages/runtime-common/tests/host-routing-validation-test.ts
@@ -263,10 +263,13 @@ const tests: SharedTests<unknown> = Object.freeze({
     async (assert) => {
       assert.strictEqual(parseRedirectStatusCode(301), 301);
       assert.strictEqual(parseRedirectStatusCode(302), 302);
-      assert.strictEqual(parseRedirectStatusCode(308), 308);
       assert.strictEqual(parseRedirectStatusCode('301'), 301);
-      assert.strictEqual(parseRedirectStatusCode(' 308 '), 308);
+      assert.strictEqual(parseRedirectStatusCode(' 302 '), 302);
+      // The method-preserving codes are deliberately unsupported: routed
+      // paths only serve GET/HEAD, so 307/308 would behave identically
+      // to 302/301.
       assert.strictEqual(parseRedirectStatusCode(307), undefined);
+      assert.strictEqual(parseRedirectStatusCode(308), undefined);
       assert.strictEqual(parseRedirectStatusCode(200), undefined);
       assert.strictEqual(parseRedirectStatusCode('perm'), undefined);
       assert.strictEqual(parseRedirectStatusCode(''), undefined);

From b898a63e8bc40d34486e9d8a2c1866e30b85fadc Mon Sep 17 00:00:00 2001
From: Buck Doyle <buck.doyle@cardstack.com>
Date: Fri, 31 Jul 2026 14:53:26 -0500
Subject: [PATCH 04/12] Carry transition query params onto SPA redirects
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The server copies the request query onto a redirect rule's target when
the target has none of its own; the SPA branch dropped it. The query is
sourced from the transition target (transition.to.queryParams), not
window.location.search — with HistoryLocation the location still shows
the URL being navigated away from while the transition is in flight.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/host/app/routes/index.gts            | 24 ++++++++++++-------
 .../host/app/services/host-mode-service.ts    | 19 +++++++++++++--
 2 files changed, 33 insertions(+), 10 deletions(-)

diff --git a/packages/host/app/routes/index.gts b/packages/host/app/routes/index.gts
index 3c8ba4c28b6..4337e4f11f0 100644
--- a/packages/host/app/routes/index.gts
+++ b/packages/host/app/routes/index.gts
@@ -76,12 +76,15 @@ export default class Card extends Route {
   // OperatorModeStateService.schedulePersist() is called (due to the fact we
   // care about the back button, see note at bottom). Because of that make sure
   // that there is as little async as possible in this model hook.
-  async model(params: {
-    authRedirect?: string;
-    cardPath?: string;
-    path: string;
-    operatorModeState: string;
-  }) {
+  async model(
+    params: {
+      authRedirect?: string;
+      cardPath?: string;
+      path: string;
+      operatorModeState: string;
+    },
+    transition: Transition,
+  ) {
     if (this.hostModeService.isActive) {
       let normalizedPath = params.path ?? '';
       // CS-10055: a routing rule in the realm config can map a bare path
@@ -89,12 +92,17 @@ export default class Card extends Route {
       // rule's target id directly; otherwise resolve the path as a card
       // URL under the host-mode origin. A redirect rule is never
       // rendered — navigate to its target instead, mirroring the 3xx
-      // the server answers for a full-page request to this path.
+      // the server answers for a full-page request to this path. The
+      // transition target's query params ride along so the two paths
+      // agree (`params` holds only the pathname).
       let routed = this.hostModeService.resolveRoutedPath(
         normalizedPath || '/',
       );
       if (routed && 'redirectTo' in routed) {
-        this.hostModeService.redirectTo(routed.redirectTo);
+        this.hostModeService.redirectTo(
+          routed.redirectTo,
+          transition.to?.queryParams,
+        );
         return;
       }
       let cardUrl =
diff --git a/packages/host/app/services/host-mode-service.ts b/packages/host/app/services/host-mode-service.ts
index e9911574669..24a75b02f63 100644
--- a/packages/host/app/services/host-mode-service.ts
+++ b/packages/host/app/services/host-mode-service.ts
@@ -170,8 +170,23 @@ export default class HostModeService extends Service {
   // redirect, which leaves no history entry for the redirecting URL.
   // Goes through ember-window-mock's `window` so tests can intercept the
   // navigation.
-  redirectTo(target: string) {
-    window.location.replace(target);
+  //
+  // `queryParams` is the transition target's query (from
+  // `transition.to.queryParams`) — NOT `window.location.search`, which
+  // with HistoryLocation still shows the URL being navigated away from
+  // while the transition is in flight. Matching serve-index's semantics,
+  // it carries over only when the redirect target declares no query of
+  // its own.
+  redirectTo(target: string, queryParams?: Record<string, unknown>) {
+    let url = new URL(target, this.hostModeOrigin ?? window.location.origin);
+    if (!url.search && queryParams) {
+      for (let [key, value] of Object.entries(queryParams)) {
+        if (value != null) {
+          url.searchParams.set(key, String(value));
+        }
+      }
+    }
+    window.location.replace(url.href);
   }
 
   get currentCardId() {

From 13ac5ddf3f6d5b29a0d48e8a4d8bd451b44bdcc1 Mon Sep 17 00:00:00 2001
From: Buck Doyle <buck.doyle@cardstack.com>
Date: Tue, 4 Aug 2026 08:18:25 -0500
Subject: [PATCH 05/12] Cover the SPA redirect path and align its query
 forwarding
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds acceptance coverage for the in-app leg of a redirect routing rule,
which had none: serve rule still renders, realm-relative and external
targets, query carry-over, and a target whose own query wins.

Two parity gaps with serve-index surfaced while writing them. The router
hydrates every declared query param onto transition.to.queryParams using
its controller default whether or not it was in the URL, so every
redirect gained a debug=false the server never sends — and internal
state, including the sid/clientSecret password-reset tokens, would have
been handed to external targets. Forwarding now drops the app's own
params, whose list moves to an exported constant. Repeated params also
serialized as tag=a,b instead of the server's tag=a&tag=b.

Realm-relative targets are joined onto the host-mode origin by
concatenation, matching how the index route builds a routed card's URL;
new URL(target, base) discarded any path the origin carries under
?hostModeOrigin= simulation.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/host/app/controllers/index.ts        |  31 +++--
 packages/host/app/routes/index.gts            |  32 ++++-
 .../host/app/services/host-mode-service.ts    |  27 ++++-
 .../host/tests/acceptance/host-mode-test.gts  | 111 ++++++++++++++++++
 4 files changed, 180 insertions(+), 21 deletions(-)

diff --git a/packages/host/app/controllers/index.ts b/packages/host/app/controllers/index.ts
index 0de27ee71ee..1445180c805 100644
--- a/packages/host/app/controllers/index.ts
+++ b/packages/host/app/controllers/index.ts
@@ -1,19 +1,26 @@
 import Controller from '@ember/controller';
 import { tracked } from '@glimmer/tracking';
 
+// The app's own query params. Exported because consumers need to tell
+// this internal routing state apart from foreign params that merely ride
+// along on the URL (e.g. `utm_source`): the router hydrates every entry
+// here onto `transition.to.queryParams`, defaults included, whether or
+// not it appeared in the URL.
+export const INDEX_QUERY_PARAMS = [
+  'authRedirect',
+  'hostModeOrigin',
+  'hostModeStack',
+  'operatorModeState',
+  // `sid` and `clientSecret` come from email verification process to reset password
+  'sid',
+  'clientSecret',
+  'card',
+  'cardPath',
+  'debug', // temporary debug param for debugging AI assistant code patches
+];
+
 export default class IndexController extends Controller {
-  queryParams = [
-    'authRedirect',
-    'hostModeOrigin',
-    'hostModeStack',
-    'operatorModeState',
-    // `sid` and `clientSecret` come from email verification process to reset password
-    'sid',
-    'clientSecret',
-    'card',
-    'cardPath',
-    'debug', // temporary debug param for debugging AI assistant code patches
-  ];
+  queryParams = INDEX_QUERY_PARAMS;
 
   @tracked authRedirect: string | null = null;
   @tracked hostModeOrigin: string | null = null;
diff --git a/packages/host/app/routes/index.gts b/packages/host/app/routes/index.gts
index 4337e4f11f0..a40edd8e679 100644
--- a/packages/host/app/routes/index.gts
+++ b/packages/host/app/routes/index.gts
@@ -12,6 +12,7 @@ import { isFileDefInstance } from '@cardstack/runtime-common/code-ref';
 
 import { Submodes } from '@cardstack/host/components/submode-switcher';
 import ENV from '@cardstack/host/config/environment';
+import { INDEX_QUERY_PARAMS } from '@cardstack/host/controllers/index';
 import type { StackItemType } from '@cardstack/host/lib/stack-item';
 
 import type BillingService from '@cardstack/host/services/billing-service';
@@ -92,16 +93,15 @@ export default class Card extends Route {
       // rule's target id directly; otherwise resolve the path as a card
       // URL under the host-mode origin. A redirect rule is never
       // rendered — navigate to its target instead, mirroring the 3xx
-      // the server answers for a full-page request to this path. The
-      // transition target's query params ride along so the two paths
-      // agree (`params` holds only the pathname).
+      // the server answers for a full-page request to this path, query
+      // string included (`params` holds only the pathname).
       let routed = this.hostModeService.resolveRoutedPath(
         normalizedPath || '/',
       );
       if (routed && 'redirectTo' in routed) {
         this.hostModeService.redirectTo(
           routed.redirectTo,
-          transition.to?.queryParams,
+          this.forwardableQueryParams(transition),
         );
         return;
       }
@@ -229,6 +229,30 @@ export default class Card extends Route {
     }
   }
 
+  // Query params to carry onto a redirect rule's target, read from the
+  // transition rather than `window.location.search` — with
+  // HistoryLocation the location still points at the URL being navigated
+  // away from while the transition is in flight.
+  //
+  // The app's own params are dropped. The router hydrates every declared
+  // param onto `transition.to.queryParams` using its controller default
+  // whether or not it was in the URL, so forwarding them blind would
+  // append junk the server never sends (`debug=false` on every redirect)
+  // and would hand internal routing state — including the `sid` /
+  // `clientSecret` password-reset tokens — to an external target.
+  // Foreign params (`utm_source` and friends) are what a redirect is
+  // actually expected to preserve, and they pass through untouched.
+  private forwardableQueryParams(
+    transition: Transition,
+  ): Record<string, unknown> {
+    let queryParams = transition.to?.queryParams ?? {};
+    return Object.fromEntries(
+      Object.entries(queryParams).filter(
+        ([key]) => !INDEX_QUERY_PARAMS.includes(key),
+      ),
+    );
+  }
+
   async afterModel(
     model: ReturnType<StoreService['get']>,
     transition: Transition,
diff --git a/packages/host/app/services/host-mode-service.ts b/packages/host/app/services/host-mode-service.ts
index 24a75b02f63..979d6c606d2 100644
--- a/packages/host/app/services/host-mode-service.ts
+++ b/packages/host/app/services/host-mode-service.ts
@@ -171,18 +171,35 @@ export default class HostModeService extends Service {
   // Goes through ember-window-mock's `window` so tests can intercept the
   // navigation.
   //
-  // `queryParams` is the transition target's query (from
-  // `transition.to.queryParams`) — NOT `window.location.search`, which
+  // `queryParams` is the transition target's query, already filtered to
+  // the params worth forwarding — NOT `window.location.search`, which
   // with HistoryLocation still shows the URL being navigated away from
   // while the transition is in flight. Matching serve-index's semantics,
   // it carries over only when the redirect target declares no query of
   // its own.
+  //
+  // A realm-relative target arrives already prefixed with the realm's
+  // mount pathname, so it is joined onto the host-mode origin by
+  // concatenation rather than `new URL(target, base)` — the latter
+  // resolves a leading-slash path against the origin ROOT, discarding
+  // any path the origin carries under `?hostModeOrigin=` simulation.
+  // This keeps redirect targets consistent with how the index route
+  // builds a routed card's URL from the same origin.
   redirectTo(target: string, queryParams?: Record<string, unknown>) {
-    let url = new URL(target, this.hostModeOrigin ?? window.location.origin);
+    let origin = this.hostModeOrigin ?? window.location.origin;
+    let url = /^https?:/i.test(target)
+      ? new URL(target)
+      : new URL(`${origin}${target.startsWith('/') ? '' : '/'}${target}`);
     if (!url.search && queryParams) {
       for (let [key, value] of Object.entries(queryParams)) {
-        if (value != null) {
-          url.searchParams.set(key, String(value));
+        if (value == null) {
+          continue;
+        }
+        // A repeated query param (`?tag=a&tag=b`) parses to an array;
+        // append each value so the target carries `tag=a&tag=b` like the
+        // server's verbatim search copy, not a collapsed `tag=a,b`.
+        for (let v of Array.isArray(value) ? value : [value]) {
+          url.searchParams.append(key, String(v));
         }
       }
     }
diff --git a/packages/host/tests/acceptance/host-mode-test.gts b/packages/host/tests/acceptance/host-mode-test.gts
index c7462e5fd7e..f510ef1a4fd 100644
--- a/packages/host/tests/acceptance/host-mode-test.gts
+++ b/packages/host/tests/acceptance/host-mode-test.gts
@@ -54,6 +54,31 @@ class StubCustomSubdomainHostModeService extends StubHostModeService {
   }
 }
 
+// The routing map normally arrives on the config meta tag the realm
+// server rewrites per request, which no test server emits — so stub the
+// getter that reads it. Paths and realm-relative targets are stored the
+// way the server injects them: prefixed with the realm's mount pathname,
+// which is `/test/` as this app sees it (`hostModeOrigin` absorbs the
+// `/user` segment above).
+class StubRoutingHostModeService extends StubHostModeService {
+  get hostRoutingMap() {
+    return [
+      { path: '/test/terms', id: `${testHostModeRealmURL}Pet/mango` },
+      { path: '/test/tos', redirectTo: '/test/terms', statusCode: 302 },
+      {
+        path: '/test/docs',
+        redirectTo: '/test/terms?section=intro',
+        statusCode: 302,
+      },
+      {
+        path: '/test/blog',
+        redirectTo: 'https://boxel.example/posts',
+        statusCode: 301,
+      },
+    ];
+  }
+}
+
 module('Acceptance | host mode tests', function (hooks) {
   setupApplicationTest(hooks);
   setupLocalIndexing(hooks);
@@ -843,6 +868,92 @@ module('Acceptance | host mode tests', function (hooks) {
     }
   });
 
+  module('with redirect routing rules', function (hooks) {
+    // A full-page request to a redirect-ruled path never reaches the SPA
+    // — serve-index answers the 3xx first. These cover the other leg: an
+    // in-app transition, where the route has to perform the redirect
+    // itself. `window` is ember-window-mock, whose `location.replace`
+    // records the URL instead of navigating.
+    let hostOrigin = removeTrailingSlash(testHostModeRealmURLWithoutRealm);
+
+    hooks.beforeEach(function (this) {
+      let owner = getOwner(this)!;
+      let ownerWithUnregister = owner as {
+        unregister?: (fullName: string) => void;
+      };
+      ownerWithUnregister.unregister?.('service:host-mode-service');
+      owner.register('service:host-mode-service', StubRoutingHostModeService);
+    });
+
+    test('a serve rule still renders its target card', async function (assert) {
+      await visit('/test/terms');
+
+      assert
+        .dom(`[data-test-host-mode-card="${testHostModeRealmURL}Pet/mango"]`)
+        .exists('the rule’s target card renders at the routed path');
+    });
+
+    test('transitioning to a redirect rule replaces the location with its target', async function (assert) {
+      await visit('/test/tos');
+
+      assert.strictEqual(
+        window.location.href,
+        `${hostOrigin}/test/terms`,
+        'the realm-relative target is resolved against the host-mode origin',
+      );
+    });
+
+    test('a redirect rule may target an external URL', async function (assert) {
+      await visit('/test/blog');
+
+      assert.strictEqual(
+        window.location.href,
+        'https://boxel.example/posts',
+        'an external target is used verbatim',
+      );
+    });
+
+    test('the source query string carries onto the redirect target', async function (assert) {
+      // Regression guard for reading the query from the transition rather
+      // than `window.location.search`: mid-transition the location still
+      // holds the URL being navigated away from, so sourcing it there
+      // would drop `utm_source` (and could forward a stale query).
+      await visit('/test/tos?utm_source=newsletter');
+
+      assert.strictEqual(
+        window.location.href,
+        `${hostOrigin}/test/terms?utm_source=newsletter`,
+        'the inbound query is preserved, matching what serve-index does',
+      );
+    });
+
+    test('a target with its own query wins over the source query', async function (assert) {
+      await visit('/test/docs?section=appendix');
+
+      assert.strictEqual(
+        window.location.href,
+        `${hostOrigin}/test/terms?section=intro`,
+        'the declared target query is left alone, matching serve-index',
+      );
+    });
+
+    test("the app's own query params are not forwarded", async function (assert) {
+      // The router hydrates every declared query param onto
+      // `transition.to.queryParams` using its controller default, present
+      // in the URL or not. Forwarding those blind would append junk the
+      // server never sends (`debug=false` on every redirect) and would
+      // hand internal state — including the `sid` / `clientSecret`
+      // password-reset tokens — to an external target.
+      await visit('/test/blog?sid=secret-token&utm_source=newsletter');
+
+      assert.strictEqual(
+        window.location.href,
+        'https://boxel.example/posts?utm_source=newsletter',
+        'foreign params ride along; app-internal ones are dropped',
+      );
+    });
+  });
+
   module('with a custom subdomain', function (hooks) {
     hooks.beforeEach(function (this) {
       let owner = getOwner(this)!;

From 6e1d9af1801fa14e0abfe19424a32639f17ec591 Mon Sep 17 00:00:00 2001
From: Buck Doyle <buck.doyle@cardstack.com>
Date: Tue, 4 Aug 2026 08:29:21 -0500
Subject: [PATCH 06/12] Guard redirect routing rules against loops
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A rule pointing at its own path, or a ring of rules pointing at each
other, answered a redirect to a URL matching the same rule again — the
client bounced until it gave up, and a permanent 301 kept doing so from
cache after the config was fixed. Nothing caught it: the target
validator is shape-only and never sees the rule's own path.

findRedirectCycles walks the relative-target graph and reports every
path in a ring. The realm drops those rules when it reads the config, so
the path resolves like any unrouted one, and the editor shows a banner
alongside the existing duplicate-path and dangling-target warnings.
Paths that only lead into a ring keep working once the ring is gone, and
an external target ends a chain. A target spelled as a full URL back to
the same site stays undetectable — the published host isn't known where
the map is built.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/base/realm-config.gts                |  22 +++
 .../realm-config-routing-rule-edit-test.gts   |  39 ++++++
 .../tests/host-routing-validation-test.ts     |  38 ++++++
 .../realm-server/tests/realm-routing-test.ts  |  26 +++-
 .../runtime-common/host-routing-validation.ts |  66 +++++++++
 packages/runtime-common/realm.ts              |  19 +++
 .../tests/host-routing-validation-test.ts     | 128 ++++++++++++++++++
 7 files changed, 337 insertions(+), 1 deletion(-)

diff --git a/packages/base/realm-config.gts b/packages/base/realm-config.gts
index a645114f9a9..19c9209de60 100644
--- a/packages/base/realm-config.gts
+++ b/packages/base/realm-config.gts
@@ -17,6 +17,7 @@ import {
   cardDefComputedFields,
   DEFAULT_REDIRECT_STATUS,
   findDuplicateRoutingPaths,
+  findRedirectCycles,
   getField,
   getFieldIcon,
   REDIRECT_STATUS_CODES,
@@ -449,6 +450,14 @@ class RealmConfigEdit extends Component<typeof RealmConfig> {
     return findDuplicateRoutingPaths(this.args.model.hostRoutingRules);
   }
 
+  // Redirect rules that chain back on themselves. The realm drops these
+  // when it reads the config — a served loop would bounce visitors until
+  // the browser gave up — so the path silently stops routing until the
+  // owner breaks the ring.
+  get redirectLoopPaths(): string[] {
+    return findRedirectCycles(this.args.model.hostRoutingRules);
+  }
+
   // Routing rules whose linked target card no longer exists. The
   // `instance` linksTo resolves to a terminal broken-link state once the
   // editor has tried to load it ('not-found' for a 404, 'error' for an
@@ -514,6 +523,19 @@ class RealmConfigEdit extends Component<typeof RealmConfig> {
                   {{/each}}
                 </div>
               {{/if}}
+              {{#if this.redirectLoopPaths.length}}
+                <div
+                  class='warning'
+                  role='status'
+                  data-test-redirect-loop-warning
+                >
+                  These redirects loop back on themselves and will not be
+                  applied:
+                  {{#each this.redirectLoopPaths as |p i|}}
+                    {{#if i}}, {{/if}}<code>{{p}}</code>
+                  {{/each}}
+                </div>
+              {{/if}}
             {{/if}}
             <FieldContainer
               @label={{startCase key}}
diff --git a/packages/host/tests/integration/components/realm-config-routing-rule-edit-test.gts b/packages/host/tests/integration/components/realm-config-routing-rule-edit-test.gts
index 7ce122c9c27..be98b3f1b6b 100644
--- a/packages/host/tests/integration/components/realm-config-routing-rule-edit-test.gts
+++ b/packages/host/tests/integration/components/realm-config-routing-rule-edit-test.gts
@@ -404,6 +404,45 @@ module(
         .exists('switching back to card restores the chooser');
     });
 
+    test('warns when redirect rules loop back on themselves', async function (assert) {
+      // The realm drops looping rules when it reads the config, so
+      // without this banner the path would just stop routing with no
+      // explanation.
+      await renderRealmConfigEdit([
+        { path: '/tos', redirectTo: '/tos' },
+        { path: '/a', redirectTo: '/b' },
+        { path: '/b', redirectTo: '/a' },
+        { path: '/fine', redirectTo: '/terms' },
+      ]);
+
+      assert
+        .dom('[data-test-redirect-loop-warning]')
+        .exists('the redirect-loop banner is shown');
+      assert
+        .dom('[data-test-redirect-loop-warning]')
+        .containsText('/tos', 'the banner names the self-redirect');
+      assert
+        .dom('[data-test-redirect-loop-warning]')
+        .containsText('/a', 'the banner names both halves of the ring');
+      assert
+        .dom('[data-test-redirect-loop-warning]')
+        .doesNotContainText(
+          '/fine',
+          'a terminating redirect is not flagged as a loop',
+        );
+    });
+
+    test('no redirect-loop warning for rules that terminate', async function (assert) {
+      await renderRealmConfigEdit([
+        { path: '/tos', redirectTo: '/terms' },
+        { path: '/blog', redirectTo: 'https://example.com/blog' },
+      ]);
+
+      assert
+        .dom('[data-test-redirect-loop-warning]')
+        .doesNotExist('no banner when nothing loops');
+    });
+
     test('typing into the path input always stores a leading slash', async function (assert) {
       await renderRealmConfigEdit([{}]);
 
diff --git a/packages/realm-server/tests/host-routing-validation-test.ts b/packages/realm-server/tests/host-routing-validation-test.ts
index 0651f840fdb..83f3bd5b167 100644
--- a/packages/realm-server/tests/host-routing-validation-test.ts
+++ b/packages/realm-server/tests/host-routing-validation-test.ts
@@ -93,6 +93,44 @@ module(basename(import.meta.filename), function () {
     });
   });
 
+  module('findRedirectCycles', function () {
+    test('findRedirectCycles: returns empty when there is nothing to loop', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+
+    test('findRedirectCycles: reports a self-redirect', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+
+    test('findRedirectCycles: reports every path in a longer ring', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+
+    test('findRedirectCycles: does not report paths that only lead into a ring', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+
+    test('findRedirectCycles: an external target ends the chain', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+
+    test('findRedirectCycles: a query or fragment on the target does not hide a loop', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+
+    test('findRedirectCycles: trailing slashes and whitespace do not hide a loop', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+
+    test('findRedirectCycles: duplicate paths resolve to the first rule', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+
+    test('findRedirectCycles: reports each looping path once across cycles', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+  });
+
   module('parseRedirectStatusCode', function () {
     test('parseRedirectStatusCode: coerces supported codes, rejects everything else', async function (assert) {
       await runSharedTest(hostRoutingValidationTests, assert, {});
diff --git a/packages/realm-server/tests/realm-routing-test.ts b/packages/realm-server/tests/realm-routing-test.ts
index ffecee77c9e..634c750c06d 100644
--- a/packages/realm-server/tests/realm-routing-test.ts
+++ b/packages/realm-server/tests/realm-routing-test.ts
@@ -65,6 +65,11 @@ function makeRoutingFixture(): Record<
             },
             { path: '/bad-redirect', redirectTo: 'javascript:alert(1)' },
             { path: '/ambiguous', redirectTo: '/elsewhere' },
+            // Loops — dropped so they can't bounce a client until it
+            // gives up: a self-redirect and a two-rule ring.
+            { path: '/self', redirectTo: '/self' },
+            { path: '/ring-a', redirectTo: '/ring-b' },
+            { path: '/ring-b', redirectTo: '/ring-a' },
           ],
         },
         relationships: {
@@ -135,7 +140,26 @@ module(basename(import.meta.filename), function () {
           },
           { path: '/ambiguous', redirectTo: '/elsewhere', statusCode: 302 },
         ],
-        'relative reference resolved against the realm root; cross-realm rule filtered; trailing-slash rule normalized to /trailing; redirect rules surface with their (default) status; the invalid javascript: target is dropped; a rule with both targets resolves as a redirect',
+        'relative reference resolved against the realm root; cross-realm rule filtered; trailing-slash rule normalized to /trailing; redirect rules surface with their (default) status; the invalid javascript: target is dropped; a rule with both targets resolves as a redirect; self-redirect and ring rules dropped',
+      );
+    });
+
+    test('drops redirect rules that loop, keeping the rest of the map', async function (assert) {
+      let map = await testRealm.getHostRoutingMap();
+      let paths = map.map((rule) => rule.path);
+
+      assert.false(paths.includes('/self'), 'the self-redirect is dropped');
+      assert.false(
+        paths.includes('/ring-a'),
+        'the first half of the two-rule ring is dropped',
+      );
+      assert.false(
+        paths.includes('/ring-b'),
+        'the second half of the two-rule ring is dropped',
+      );
+      assert.true(
+        paths.includes('/tos'),
+        'a terminating redirect rule is unaffected',
       );
     });
 
diff --git a/packages/runtime-common/host-routing-validation.ts b/packages/runtime-common/host-routing-validation.ts
index a9205c1e809..d45cb04b53a 100644
--- a/packages/runtime-common/host-routing-validation.ts
+++ b/packages/runtime-common/host-routing-validation.ts
@@ -159,6 +159,72 @@ export function parseRedirectStatusCode(
     : undefined;
 }
 
+/**
+ * Returns the paths whose redirect rules chain back on themselves, in
+ * the order the cycles were discovered — a self-redirect
+ * (`/tos` → `/tos`) or a longer ring (`/a` → `/b` → `/a`). Left
+ * unguarded, each one answers a redirect to a URL that matches the same
+ * rule again, so the client bounces until it gives up
+ * (`ERR_TOO_MANY_REDIRECTS`) — and a permanent 301 keeps doing so from
+ * cache after the rule is fixed.
+ *
+ * Only realm-relative targets form edges: an external `http(s)` target
+ * leaves the realm, so it ends the chain. Targets are compared by
+ * pathname in normalized form, so a query string or a trailing slash on
+ * the target doesn't disguise a loop. Paths that merely *lead into* a
+ * cycle are not reported — dropping the ring itself is enough to make
+ * them resolve.
+ *
+ * A realm cannot reach its own paths through an external URL as far as
+ * this can tell (the published host isn't known here), so a target
+ * spelled as a full URL back to the same site stays undetected.
+ */
+export function findRedirectCycles(
+  rules:
+    | ReadonlyArray<{ path?: string | null; redirectTo?: string | null }>
+    | null
+    | undefined,
+): string[] {
+  if (!rules) return [];
+  // path -> the path it redirects to. Duplicate paths keep the first
+  // rule, matching how the routing map's `.find()` resolves them.
+  let edges = new Map<string, string>();
+  for (let rule of rules) {
+    let path = rule?.path?.trim();
+    let target = rule?.redirectTo?.trim();
+    if (!path || !target || ABSOLUTE_URL_PATTERN.test(target)) continue;
+    let from = normalizeRoutingPath(path);
+    if (edges.has(from)) continue;
+    // Compare pathnames only: the target's own query/fragment doesn't
+    // change which rule the redirected request matches.
+    let targetPath = target.split('#')[0].split('?')[0];
+    edges.set(from, normalizeRoutingPath(targetPath));
+  }
+
+  let cyclic: string[] = [];
+  let seenCyclic = new Set<string>();
+  for (let start of edges.keys()) {
+    // Walk the chain from `start`, recording visit order, until it ends
+    // (no outgoing edge) or revisits a node on this walk.
+    let positions = new Map<string, number>();
+    let chain: string[] = [];
+    let node: string | undefined = start;
+    while (node !== undefined && !positions.has(node)) {
+      positions.set(node, chain.length);
+      chain.push(node);
+      node = edges.get(node);
+    }
+    if (node === undefined) continue; // chain terminated, no loop
+    for (let i = positions.get(node)!; i < chain.length; i++) {
+      if (!seenCyclic.has(chain[i])) {
+        seenCyclic.add(chain[i]);
+        cyclic.push(chain[i]);
+      }
+    }
+  }
+  return cyclic;
+}
+
 /**
  * Returns the set of non-empty paths that appear on more than one
  * routing rule, in insertion order. Empty paths are ignored — they
diff --git a/packages/runtime-common/realm.ts b/packages/runtime-common/realm.ts
index 0bad0f20619..f3a673e06e8 100644
--- a/packages/runtime-common/realm.ts
+++ b/packages/runtime-common/realm.ts
@@ -50,6 +50,8 @@ import {
 import { normalizeRelationships } from './relationship-utils.ts';
 import {
   DEFAULT_REDIRECT_STATUS,
+  findRedirectCycles,
+  isRedirectRoutingRule,
   normalizeRoutingPath,
   parseRedirectStatusCode,
   validateRedirectTarget,
@@ -6923,6 +6925,23 @@ export class Realm {
         }
         return [{ path: normalizedPath, id }];
       });
+      // Drop redirect rules that chain back on themselves. Serving them
+      // would bounce the client between URLs until it gives up, and a
+      // permanent 301 would keep doing so from cache after the config is
+      // fixed. Dropped, the path resolves like any unrouted one. Only
+      // the rules forming the ring go — a rule pointing INTO it resolves
+      // once the ring is gone.
+      let looping = new Set(findRedirectCycles(map));
+      if (looping.size > 0) {
+        for (let path of looping) {
+          this.#log.warn(
+            `dropping host routing rule for path "${path}" — its redirect target loops back to itself`,
+          );
+        }
+        map = map.filter(
+          (rule) => !(isRedirectRoutingRule(rule) && looping.has(rule.path)),
+        );
+      }
       return (this.#cachedHostRoutingMap = map);
     } catch (e) {
       this.#log.warn(
diff --git a/packages/runtime-common/tests/host-routing-validation-test.ts b/packages/runtime-common/tests/host-routing-validation-test.ts
index 58c8679b421..da6c5f27828 100644
--- a/packages/runtime-common/tests/host-routing-validation-test.ts
+++ b/packages/runtime-common/tests/host-routing-validation-test.ts
@@ -1,5 +1,6 @@
 import {
   findDuplicateRoutingPaths,
+  findRedirectCycles,
   normalizeRoutingPath,
   parseRedirectStatusCode,
   validateRedirectTarget,
@@ -259,6 +260,133 @@ const tests: SharedTests<unknown> = Object.freeze({
       );
     },
 
+  'findRedirectCycles: returns empty when there is nothing to loop': async (
+    assert,
+  ) => {
+    assert.deepEqual(findRedirectCycles(null), []);
+    assert.deepEqual(findRedirectCycles(undefined), []);
+    assert.deepEqual(findRedirectCycles([]), []);
+    assert.deepEqual(findRedirectCycles([{ path: '/terms' }]), []);
+    assert.deepEqual(
+      findRedirectCycles([{ path: '/tos', redirectTo: '/terms' }]),
+      [],
+      'a redirect to a path with no rule of its own terminates',
+    );
+  },
+
+  'findRedirectCycles: reports a self-redirect': async (assert) => {
+    assert.deepEqual(
+      findRedirectCycles([
+        { path: '/tos', redirectTo: '/tos' },
+        { path: '/terms' },
+      ]),
+      ['/tos'],
+    );
+  },
+
+  'findRedirectCycles: reports every path in a longer ring': async (assert) => {
+    assert.deepEqual(
+      findRedirectCycles([
+        { path: '/a', redirectTo: '/b' },
+        { path: '/b', redirectTo: '/a' },
+      ]),
+      ['/a', '/b'],
+    );
+    assert.deepEqual(
+      findRedirectCycles([
+        { path: '/a', redirectTo: '/b' },
+        { path: '/b', redirectTo: '/c' },
+        { path: '/c', redirectTo: '/a' },
+      ]),
+      ['/a', '/b', '/c'],
+    );
+  },
+
+  'findRedirectCycles: does not report paths that only lead into a ring':
+    async (assert) => {
+      // Dropping the ring is enough — '/x' then resolves like any
+      // redirect whose target has no rule.
+      assert.deepEqual(
+        findRedirectCycles([
+          { path: '/x', redirectTo: '/a' },
+          { path: '/a', redirectTo: '/b' },
+          { path: '/b', redirectTo: '/a' },
+        ]),
+        ['/a', '/b'],
+      );
+    },
+
+  'findRedirectCycles: an external target ends the chain': async (assert) => {
+    assert.deepEqual(
+      findRedirectCycles([
+        { path: '/a', redirectTo: 'https://example.com/a' },
+        { path: '/b', redirectTo: '/a' },
+      ]),
+      [],
+      'leaving the realm cannot loop back through the routing map',
+    );
+  },
+
+  'findRedirectCycles: a query or fragment on the target does not hide a loop':
+    async (assert) => {
+      assert.deepEqual(
+        findRedirectCycles([{ path: '/tos', redirectTo: '/tos?ref=1' }]),
+        ['/tos'],
+      );
+      assert.deepEqual(
+        findRedirectCycles([{ path: '/tos', redirectTo: '/tos#section' }]),
+        ['/tos'],
+      );
+    },
+
+  'findRedirectCycles: trailing slashes and whitespace do not hide a loop':
+    async (assert) => {
+      assert.deepEqual(
+        findRedirectCycles([{ path: '/tos', redirectTo: '/tos/' }]),
+        ['/tos'],
+      );
+      assert.deepEqual(
+        findRedirectCycles([{ path: '  /tos/  ', redirectTo: '  /tos  ' }]),
+        ['/tos'],
+      );
+    },
+
+  'findRedirectCycles: duplicate paths resolve to the first rule': async (
+    assert,
+  ) => {
+    // The routing map's `.find()` makes the second rule unreachable, so
+    // only the first one's target can form an edge.
+    assert.deepEqual(
+      findRedirectCycles([
+        { path: '/a', redirectTo: '/terms' },
+        { path: '/a', redirectTo: '/a' },
+      ]),
+      [],
+      'the shadowed self-redirect never resolves, so it cannot loop',
+    );
+    assert.deepEqual(
+      findRedirectCycles([
+        { path: '/a', redirectTo: '/a' },
+        { path: '/a', redirectTo: '/terms' },
+      ]),
+      ['/a'],
+      'the reachable rule is the looping one',
+    );
+  },
+
+  'findRedirectCycles: reports each looping path once across cycles': async (
+    assert,
+  ) => {
+    assert.deepEqual(
+      findRedirectCycles([
+        { path: '/a', redirectTo: '/b' },
+        { path: '/b', redirectTo: '/a' },
+        { path: '/c', redirectTo: '/c' },
+      ]),
+      ['/a', '/b', '/c'],
+    );
+  },
+
   'parseRedirectStatusCode: coerces supported codes, rejects everything else':
     async (assert) => {
       assert.strictEqual(parseRedirectStatusCode(301), 301);

From 08597ca8d46ba83d1d60e16ca3b2c36bfc7b9c88 Mon Sep 17 00:00:00 2001
From: Buck Doyle <buck.doyle@cardstack.com>
Date: Tue, 4 Aug 2026 08:49:33 -0500
Subject: [PATCH 07/12] Resolve SPA redirects against the document origin
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

hostModeOrigin returns the ?hostModeOrigin= query param verbatim
whenever one is present, so using it as the base for a realm-relative
redirect target made location.replace() a navigation sink on visitor
input: the param is a declared query param and sticks across in-app
transitions, sending every redirect rule to an origin the visitor picked.
An empty ?hostModeOrigin= yielded '', which is not nullish, so the
fallback beside it never ran and URL construction threw inside the model
hook instead.

Realm-relative targets now resolve against window.location.origin, the
way a browser resolves a Location: /path header. The two values are
identical in host mode — only the simulation affordance separates them,
and a simulated session should stay on the page it runs from.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../host/app/services/host-mode-service.ts    | 16 +++---
 .../host/tests/acceptance/host-mode-test.gts  | 50 +++++++++++++++++--
 2 files changed, 54 insertions(+), 12 deletions(-)

diff --git a/packages/host/app/services/host-mode-service.ts b/packages/host/app/services/host-mode-service.ts
index 979d6c606d2..49d3c8bab65 100644
--- a/packages/host/app/services/host-mode-service.ts
+++ b/packages/host/app/services/host-mode-service.ts
@@ -179,17 +179,17 @@ export default class HostModeService extends Service {
   // its own.
   //
   // A realm-relative target arrives already prefixed with the realm's
-  // mount pathname, so it is joined onto the host-mode origin by
-  // concatenation rather than `new URL(target, base)` — the latter
-  // resolves a leading-slash path against the origin ROOT, discarding
-  // any path the origin carries under `?hostModeOrigin=` simulation.
-  // This keeps redirect targets consistent with how the index route
-  // builds a routed card's URL from the same origin.
+  // mount pathname, and resolves against the document's own origin —
+  // what a browser does with a `Location: /path` header. Deliberately
+  // NOT `hostModeOrigin`: that returns the `?hostModeOrigin=` query
+  // param verbatim whenever it is present, which would let a visitor
+  // pick the origin this navigates to. The two are the same value in
+  // host mode anyway; only the simulation affordance separates them,
+  // and a simulated session should stay on the page it is running from.
   redirectTo(target: string, queryParams?: Record<string, unknown>) {
-    let origin = this.hostModeOrigin ?? window.location.origin;
     let url = /^https?:/i.test(target)
       ? new URL(target)
-      : new URL(`${origin}${target.startsWith('/') ? '' : '/'}${target}`);
+      : new URL(target, window.location.origin);
     if (!url.search && queryParams) {
       for (let [key, value] of Object.entries(queryParams)) {
         if (value == null) {
diff --git a/packages/host/tests/acceptance/host-mode-test.gts b/packages/host/tests/acceptance/host-mode-test.gts
index f510ef1a4fd..467da2b8399 100644
--- a/packages/host/tests/acceptance/host-mode-test.gts
+++ b/packages/host/tests/acceptance/host-mode-test.gts
@@ -79,6 +79,16 @@ class StubRoutingHostModeService extends StubHostModeService {
   }
 }
 
+// `hostModeOrigin` is visitor-controllable — it hands back the
+// `?hostModeOrigin=` query param verbatim whenever one is present — so a
+// redirect must never resolve a realm-relative target against it. This
+// stub returns an origin no redirect may land on.
+class StubHijackedOriginHostModeService extends StubRoutingHostModeService {
+  get hostModeOrigin() {
+    return 'https://attacker.example';
+  }
+}
+
 module('Acceptance | host mode tests', function (hooks) {
   setupApplicationTest(hooks);
   setupLocalIndexing(hooks);
@@ -874,7 +884,11 @@ module('Acceptance | host mode tests', function (hooks) {
     // in-app transition, where the route has to perform the redirect
     // itself. `window` is ember-window-mock, whose `location.replace`
     // records the URL instead of navigating.
-    let hostOrigin = removeTrailingSlash(testHostModeRealmURLWithoutRealm);
+    //
+    // A realm-relative target resolves against the document's own
+    // origin, the way a browser resolves a `Location: /path` header.
+    // Read inside each test — the window mock is installed per-test, so
+    // capturing it out here would read the real page's origin instead.
 
     hooks.beforeEach(function (this) {
       let owner = getOwner(this)!;
@@ -898,7 +912,7 @@ module('Acceptance | host mode tests', function (hooks) {
 
       assert.strictEqual(
         window.location.href,
-        `${hostOrigin}/test/terms`,
+        `${window.location.origin}/test/terms`,
         'the realm-relative target is resolved against the host-mode origin',
       );
     });
@@ -922,7 +936,7 @@ module('Acceptance | host mode tests', function (hooks) {
 
       assert.strictEqual(
         window.location.href,
-        `${hostOrigin}/test/terms?utm_source=newsletter`,
+        `${window.location.origin}/test/terms?utm_source=newsletter`,
         'the inbound query is preserved, matching what serve-index does',
       );
     });
@@ -932,11 +946,39 @@ module('Acceptance | host mode tests', function (hooks) {
 
       assert.strictEqual(
         window.location.href,
-        `${hostOrigin}/test/terms?section=intro`,
+        `${window.location.origin}/test/terms?section=intro`,
         'the declared target query is left alone, matching serve-index',
       );
     });
 
+    test('a hijacked hostModeOrigin cannot steer the redirect', async function (assert) {
+      // `?hostModeOrigin=https://evil.example` sticks across in-app
+      // transitions (it is a declared query param), so resolving a
+      // realm-relative target against `hostModeOrigin` would turn every
+      // redirect rule into an open redirect to a visitor-chosen origin.
+      let owner = getOwner(this)!;
+      let ownerWithUnregister = owner as {
+        unregister?: (fullName: string) => void;
+      };
+      ownerWithUnregister.unregister?.('service:host-mode-service');
+      owner.register(
+        'service:host-mode-service',
+        StubHijackedOriginHostModeService,
+      );
+
+      await visit('/test/tos');
+
+      assert.strictEqual(
+        window.location.href,
+        `${window.location.origin}/test/terms`,
+        'the redirect stays on the document origin',
+      );
+      assert.notOk(
+        window.location.href.startsWith('https://attacker.example'),
+        'hostModeOrigin is not used as the redirect base',
+      );
+    });
+
     test("the app's own query params are not forwarded", async function (assert) {
       // The router hydrates every declared query param onto
       // `transition.to.queryParams` using its controller default, present

From fe77e5a0f4f00e31d899ee6792ee0471b07060e4 Mon Sep 17 00:00:00 2001
From: Buck Doyle <buck.doyle@cardstack.com>
Date: Tue, 4 Aug 2026 08:55:09 -0500
Subject: [PATCH 08/12] Stop redirect rules handing host-app query params to
 their target
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The SPA already dropped these; the server still forwarded the request's
search verbatim, so the two answered different URLs for the same inbound
request. A redirect target may be an external site, and sid/clientSecret
are password-reset tokens — neither side should pass them on. The rest
are meaningless off the page that owns them.

The list moves to runtime-common so the index controller and serve-index
read the same one, with foreignQueryParams as the shared filter. It
round-trips through URLSearchParams, so repeated keys stay repeated and
a query made up entirely of app params leaves no empty ? behind.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/host/app/controllers/index.ts        | 24 +++-------
 packages/host/app/routes/index.gts            | 19 ++++----
 packages/realm-server/handlers/serve-index.ts | 12 ++++-
 .../tests/host-routing-validation-test.ts     | 14 ++++++
 .../server-endpoints/index-responses-test.ts  | 33 +++++++++++++
 .../runtime-common/host-routing-validation.ts | 43 +++++++++++++++++
 .../tests/host-routing-validation-test.ts     | 46 +++++++++++++++++++
 7 files changed, 161 insertions(+), 30 deletions(-)

diff --git a/packages/host/app/controllers/index.ts b/packages/host/app/controllers/index.ts
index 1445180c805..5a0d1cc9fd9 100644
--- a/packages/host/app/controllers/index.ts
+++ b/packages/host/app/controllers/index.ts
@@ -1,26 +1,14 @@
 import Controller from '@ember/controller';
 import { tracked } from '@glimmer/tracking';
 
-// The app's own query params. Exported because consumers need to tell
-// this internal routing state apart from foreign params that merely ride
-// along on the URL (e.g. `utm_source`): the router hydrates every entry
-// here onto `transition.to.queryParams`, defaults included, whether or
-// not it appeared in the URL.
-export const INDEX_QUERY_PARAMS = [
-  'authRedirect',
-  'hostModeOrigin',
-  'hostModeStack',
-  'operatorModeState',
-  // `sid` and `clientSecret` come from email verification process to reset password
-  'sid',
-  'clientSecret',
-  'card',
-  'cardPath',
-  'debug', // temporary debug param for debugging AI assistant code patches
-];
+import { HOST_APP_QUERY_PARAMS } from '@cardstack/runtime-common';
 
 export default class IndexController extends Controller {
-  queryParams = INDEX_QUERY_PARAMS;
+  // Declared in runtime-common so the realm server reads the same list
+  // when it decides which params a redirect rule may carry onto its
+  // target. `debug` is a temporary param for debugging AI assistant code
+  // patches.
+  queryParams = HOST_APP_QUERY_PARAMS;
 
   @tracked authRedirect: string | null = null;
   @tracked hostModeOrigin: string | null = null;
diff --git a/packages/host/app/routes/index.gts b/packages/host/app/routes/index.gts
index a40edd8e679..45e78d380b3 100644
--- a/packages/host/app/routes/index.gts
+++ b/packages/host/app/routes/index.gts
@@ -8,11 +8,11 @@ import { isTesting } from '@embroider/macros';
 import window from 'ember-window-mock';
 import stringify from 'safe-stable-stringify';
 
+import { HOST_APP_QUERY_PARAMS } from '@cardstack/runtime-common';
 import { isFileDefInstance } from '@cardstack/runtime-common/code-ref';
 
 import { Submodes } from '@cardstack/host/components/submode-switcher';
 import ENV from '@cardstack/host/config/environment';
-import { INDEX_QUERY_PARAMS } from '@cardstack/host/controllers/index';
 import type { StackItemType } from '@cardstack/host/lib/stack-item';
 
 import type BillingService from '@cardstack/host/services/billing-service';
@@ -234,21 +234,20 @@ export default class Card extends Route {
   // HistoryLocation the location still points at the URL being navigated
   // away from while the transition is in flight.
   //
-  // The app's own params are dropped. The router hydrates every declared
-  // param onto `transition.to.queryParams` using its controller default
-  // whether or not it was in the URL, so forwarding them blind would
-  // append junk the server never sends (`debug=false` on every redirect)
-  // and would hand internal routing state — including the `sid` /
-  // `clientSecret` password-reset tokens — to an external target.
-  // Foreign params (`utm_source` and friends) are what a redirect is
-  // actually expected to preserve, and they pass through untouched.
+  // The app's own params are dropped, matching what serve-index forwards
+  // on the equivalent HTTP redirect. On this side there is an extra
+  // reason to: the router hydrates every declared param onto
+  // `transition.to.queryParams` using its controller default whether or
+  // not it was in the URL, so forwarding them blind would append values
+  // that were never there (`debug=false` on every redirect). Foreign
+  // params (`utm_source` and friends) pass through untouched.
   private forwardableQueryParams(
     transition: Transition,
   ): Record<string, unknown> {
     let queryParams = transition.to?.queryParams ?? {};
     return Object.fromEntries(
       Object.entries(queryParams).filter(
-        ([key]) => !INDEX_QUERY_PARAMS.includes(key),
+        ([key]) => !HOST_APP_QUERY_PARAMS.includes(key),
       ),
     );
   }
diff --git a/packages/realm-server/handlers/serve-index.ts b/packages/realm-server/handlers/serve-index.ts
index d8619988b41..0268334396d 100644
--- a/packages/realm-server/handlers/serve-index.ts
+++ b/packages/realm-server/handlers/serve-index.ts
@@ -7,6 +7,7 @@ import type {
   Realm,
 } from '@cardstack/runtime-common';
 import {
+  foreignQueryParams,
   hasExtension,
   isRedirectRoutingRule,
   logger,
@@ -408,7 +409,11 @@ export function createServeIndex(deps: ServeIndexDeps): ServeIndexHandlers {
           // rule's own `path` is mounted; extra leading slashes are
           // collapsed so a target can never be read as protocol-
           // relative. The request's query string carries over unless
-          // the target declares its own.
+          // the target declares its own — minus the host app's own
+          // params, which a redirect has no business handing on: the
+          // target may be an external site, and `sid` / `clientSecret`
+          // are password-reset tokens. The SPA drops the same list on
+          // its in-app navigation, so both answer the same URL.
           let { redirectTo, statusCode } = matched.rule;
           let target: URL;
           if (/^https?:/i.test(redirectTo)) {
@@ -421,7 +426,10 @@ export function createServeIndex(deps: ServeIndexDeps): ServeIndexHandlers {
             );
           }
           if (requestURL.search && !target.search) {
-            target.search = requestURL.search;
+            let forwarded = foreignQueryParams(requestURL.search);
+            if (forwarded) {
+              target.search = forwarded;
+            }
           }
           ctxt.redirect(target.href);
           ctxt.status = statusCode;
diff --git a/packages/realm-server/tests/host-routing-validation-test.ts b/packages/realm-server/tests/host-routing-validation-test.ts
index 83f3bd5b167..4314b3d01ed 100644
--- a/packages/realm-server/tests/host-routing-validation-test.ts
+++ b/packages/realm-server/tests/host-routing-validation-test.ts
@@ -131,6 +131,20 @@ module(basename(import.meta.filename), function () {
     });
   });
 
+  module('foreignQueryParams', function () {
+    test('foreignQueryParams: keeps params the host app does not own', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+
+    test('foreignQueryParams: drops the host app’s own params', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+
+    test('foreignQueryParams: preserves repeated keys as repeated keys', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+  });
+
   module('parseRedirectStatusCode', function () {
     test('parseRedirectStatusCode: coerces supported codes, rejects everything else', async function (assert) {
       await runSharedTest(hostRoutingValidationTests, assert, {});
diff --git a/packages/realm-server/tests/server-endpoints/index-responses-test.ts b/packages/realm-server/tests/server-endpoints/index-responses-test.ts
index 2d5efd91f1a..a410b870153 100644
--- a/packages/realm-server/tests/server-endpoints/index-responses-test.ts
+++ b/packages/realm-server/tests/server-endpoints/index-responses-test.ts
@@ -1935,6 +1935,39 @@ module(`server-endpoints/${basename(import.meta.filename)}`, function () {
         );
       });
 
+      test('a redirect rule does not hand the host app’s own query params to its target', async function (assert) {
+        // `sid` / `clientSecret` are password-reset tokens, and this
+        // target is a third-party site. The SPA drops the same list on
+        // its in-app navigation, so both answer the same URL.
+        let response = await request
+          .get(
+            `${publishedRealmPath}external?sid=secret-token&clientSecret=secret-secret&utm_source=newsletter`,
+          )
+          .set('Host', publishedRealmHost)
+          .set('Accept', 'text/html');
+
+        assert.strictEqual(response.status, 301);
+        assert.strictEqual(
+          response.headers['location'],
+          'https://example.com/landing?utm_source=newsletter',
+          'only the foreign param rides along',
+        );
+      });
+
+      test('a redirect rule drops a query string made up entirely of the host app’s params', async function (assert) {
+        let response = await request
+          .get(`${publishedRealmPath}tos?hostModeStack=%5B%5D`)
+          .set('Host', publishedRealmHost)
+          .set('Accept', 'text/html');
+
+        assert.strictEqual(response.status, 302);
+        assert.strictEqual(
+          response.headers['location'],
+          `http://${publishedRealmHost}${publishedRealmPath}terms`,
+          'no empty ? is appended when nothing survives filtering',
+        );
+      });
+
       test('a redirect rule may target an external URL with an explicit status code', async function (assert) {
         let response = await request
           .get(`${publishedRealmPath}external`)
diff --git a/packages/runtime-common/host-routing-validation.ts b/packages/runtime-common/host-routing-validation.ts
index d45cb04b53a..baa3d003844 100644
--- a/packages/runtime-common/host-routing-validation.ts
+++ b/packages/runtime-common/host-routing-validation.ts
@@ -11,6 +11,49 @@ const VALID_PATH_PATTERN = /^\/(?:[A-Za-z0-9._~/-]|%[0-9A-Fa-f]{2})*$/;
 // exclusively (card mutations live on the JSON API, not these URLs), so
 // the method-preserving codes (307/308) would behave identically to
 // their plain counterparts and just clutter the choice.
+// The host app's own query params — the routing state it reads off the
+// URL, as declared by its index controller. Shared so a redirect rule
+// can tell this internal state apart from foreign params that merely
+// ride along (`utm_source` and friends): a redirect carries the foreign
+// ones onto its target and drops these, on both the server's 3xx and the
+// SPA's in-app navigation.
+//
+// Two reasons they are dropped. Some are sensitive — `sid` and
+// `clientSecret` are password-reset tokens — and a redirect target may
+// be an external site, which would receive them in its own URL. The
+// rest are meaningless off the page that owns them. The client has a
+// third reason: its router hydrates every declared param onto the
+// transition using the controller's default, so forwarding blind would
+// append values that were never in the URL at all.
+export const HOST_APP_QUERY_PARAMS = [
+  'authRedirect',
+  'hostModeOrigin',
+  'hostModeStack',
+  'operatorModeState',
+  // `sid` and `clientSecret` come from the email verification process to
+  // reset a password
+  'sid',
+  'clientSecret',
+  'card',
+  'cardPath',
+  'debug',
+];
+
+/**
+ * Strips the host app's own query params from `search`, returning the
+ * remainder as a query string without its leading `?` (empty when
+ * nothing survives). Values round-trip through `URLSearchParams`, so
+ * repeated keys are preserved as repeated keys and encoding is
+ * normalized to its standard form.
+ */
+export function foreignQueryParams(search: string): string {
+  let params = new URLSearchParams(search);
+  for (let key of HOST_APP_QUERY_PARAMS) {
+    params.delete(key);
+  }
+  return params.toString();
+}
+
 export const REDIRECT_STATUS_CODES = [301, 302] as const;
 export type RedirectStatusCode = (typeof REDIRECT_STATUS_CODES)[number];
 
diff --git a/packages/runtime-common/tests/host-routing-validation-test.ts b/packages/runtime-common/tests/host-routing-validation-test.ts
index da6c5f27828..050e7a343df 100644
--- a/packages/runtime-common/tests/host-routing-validation-test.ts
+++ b/packages/runtime-common/tests/host-routing-validation-test.ts
@@ -1,6 +1,7 @@
 import {
   findDuplicateRoutingPaths,
   findRedirectCycles,
+  foreignQueryParams,
   normalizeRoutingPath,
   parseRedirectStatusCode,
   validateRedirectTarget,
@@ -387,6 +388,51 @@ const tests: SharedTests<unknown> = Object.freeze({
     );
   },
 
+  'foreignQueryParams: keeps params the host app does not own': async (
+    assert,
+  ) => {
+    assert.strictEqual(
+      foreignQueryParams('?utm_source=newsletter'),
+      'utm_source=newsletter',
+    );
+    assert.strictEqual(
+      foreignQueryParams('utm_source=newsletter&ref=twitter'),
+      'utm_source=newsletter&ref=twitter',
+      'the leading ? is optional',
+    );
+    assert.strictEqual(foreignQueryParams(''), '');
+  },
+
+  'foreignQueryParams: drops the host app’s own params': async (assert) => {
+    // `sid` / `clientSecret` are password-reset tokens and a redirect
+    // target may be an external site.
+    assert.strictEqual(
+      foreignQueryParams('?sid=abc&clientSecret=xyz&utm_source=newsletter'),
+      'utm_source=newsletter',
+    );
+    assert.strictEqual(
+      foreignQueryParams('?hostModeStack=%5B%5D&operatorModeState=%7B%7D'),
+      '',
+      'nothing survives when every param is the app’s own',
+    );
+    assert.strictEqual(
+      foreignQueryParams('?hostModeOrigin=https://evil.example'),
+      '',
+    );
+  },
+
+  'foreignQueryParams: preserves repeated keys as repeated keys': async (
+    assert,
+  ) => {
+    // Collapsing these to `tag=a,b` would diverge from what the server
+    // received and from what the SPA rebuilds.
+    assert.strictEqual(foreignQueryParams('?tag=a&tag=b'), 'tag=a&tag=b');
+    assert.strictEqual(
+      foreignQueryParams('?tag=a&sid=secret&tag=b'),
+      'tag=a&tag=b',
+    );
+  },
+
   'parseRedirectStatusCode: coerces supported codes, rejects everything else':
     async (assert) => {
       assert.strictEqual(parseRedirectStatusCode(301), 301);

From f70fd5302086238288bf711df06a150de80fbecd Mon Sep 17 00:00:00 2001
From: Buck Doyle <buck.doyle@cardstack.com>
Date: Tue, 4 Aug 2026 09:02:00 -0500
Subject: [PATCH 09/12] Derive the routing rule editor's kind from the rule
 itself

The tracked override was set on every toggle and never cleared, so once
clicked it shadowed the model for the life of the component. With the
config card open in two places, clearing a redirect in one left the
other showing an empty redirect editor, where the next keystroke wrote a
redirectTo that beats the instance the first had chosen.

Its justification was wrong: setField writes to the data bucket and
calls notifyCardTracking inline, so a field write is readable and
rendered without a mirror in component state. StringField has no empty
value, so an unset redirectTo reads as undefined and the seeded empty
string still reads as a redirect.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/base/realm-config.gts                | 22 ++++++--------
 .../realm-config-routing-rule-edit-test.gts   | 30 ++++++++++++++++++-
 2 files changed, 38 insertions(+), 14 deletions(-)

diff --git a/packages/base/realm-config.gts b/packages/base/realm-config.gts
index 19c9209de60..a1e9c1aae80 100644
--- a/packages/base/realm-config.gts
+++ b/packages/base/realm-config.gts
@@ -38,7 +38,6 @@ import LinkIcon from '@cardstack/boxel-icons/link';
 import { fn } from '@ember/helper';
 import { action } from '@ember/object';
 import type Owner from '@ember/owner';
-import { tracked } from '@glimmer/tracking';
 import { startCase } from 'lodash-es';
 import type { FieldsTypeFor } from './card-api';
 
@@ -76,13 +75,6 @@ class RoutingRuleAtom extends Component<typeof RoutingRuleField> {
 let routingRuleKindGroupNumber = 0;
 
 class RoutingRuleEdit extends Component<typeof RoutingRuleField> {
-  // Which target editor is showing. Backed by the data: a rule whose
-  // `redirectTo` is non-null (empty string included — `setKind` seeds
-  // '' so the choice survives a reload) is a redirect rule. The tracked
-  // override exists only so the toggle responds instantly while the
-  // model write settles.
-  @tracked private kindOverride: 'card' | 'redirect' | null = null;
-
   private kindItems: { id: 'card' | 'redirect'; text: string }[] = [
     { id: 'card', text: 'Render a card' },
     { id: 'redirect', text: 'Redirect' },
@@ -138,11 +130,16 @@ class RoutingRuleEdit extends Component<typeof RoutingRuleField> {
     this.args.model.path = `/${trimmed}`;
   }
 
+  // Which target editor is showing, derived from the data alone: a rule
+  // carrying a `redirectTo` is a redirect rule. `setKind` seeds an empty
+  // string when switching, which reads as a redirect (the field is unset
+  // as `undefined`, and `StringField` has no empty value that would
+  // blur the two) and so survives a reload. Deliberately not mirrored
+  // into component state: field writes notify Glimmer synchronously, so
+  // a copy would buy nothing and would go on shadowing the model after
+  // anything but this toggle changed it.
   get kind(): 'card' | 'redirect' {
-    return (
-      this.kindOverride ??
-      (this.args.model.redirectTo != null ? 'redirect' : 'card')
-    );
+    return this.args.model.redirectTo != null ? 'redirect' : 'card';
   }
 
   get isRedirect(): boolean {
@@ -154,7 +151,6 @@ class RoutingRuleEdit extends Component<typeof RoutingRuleField> {
   // but only a hand-edited realm.json can get into that state).
   @action
   setKind(kind: 'card' | 'redirect') {
-    this.kindOverride = kind;
     if (kind === 'redirect') {
       this.args.model.instance = undefined;
       if (this.args.model.redirectTo == null) {
diff --git a/packages/host/tests/integration/components/realm-config-routing-rule-edit-test.gts b/packages/host/tests/integration/components/realm-config-routing-rule-edit-test.gts
index be98b3f1b6b..854b24a761f 100644
--- a/packages/host/tests/integration/components/realm-config-routing-rule-edit-test.gts
+++ b/packages/host/tests/integration/components/realm-config-routing-rule-edit-test.gts
@@ -1,4 +1,4 @@
-import { waitFor, click, fillIn } from '@ember/test-helpers';
+import { waitFor, click, fillIn, settled } from '@ember/test-helpers';
 import GlimmerComponent from '@glimmer/component';
 
 import { getService } from '@universal-ember/test-support';
@@ -404,6 +404,34 @@ module(
         .exists('switching back to card restores the chooser');
     });
 
+    test('the shown editor follows the model when the rule changes elsewhere', async function (assert) {
+      // The same config card can be open in more than one place. The
+      // editor derives which target editor to show from the rule itself,
+      // so a change made elsewhere is reflected here; a copy of the
+      // choice held in component state would shadow it forever, and the
+      // next keystroke would write a `redirectTo` that silently beats
+      // the instance the other editor had chosen.
+      await renderRealmConfigEdit([{ path: '/tos', redirectTo: '/terms' }]);
+
+      assert
+        .dom('[data-test-redirect-input]')
+        .exists('starts on the redirect editor');
+
+      let store = getService('store');
+      let realmConfig = (await store.get(`${testRealmURL}realm`)) as any;
+      realmConfig.hostRoutingRules[0].redirectTo = undefined;
+      await settled();
+
+      assert
+        .dom('[data-test-redirect-input]')
+        .doesNotExist('clearing the target elsewhere flips this editor back');
+      assert
+        .dom(
+          '[data-test-routing-rule-kind] [data-test-boxel-radio-option-id="card"] input[type="radio"]',
+        )
+        .isChecked('the toggle follows the model rather than a stale copy');
+    });
+
     test('warns when redirect rules loop back on themselves', async function (assert) {
       // The realm drops looping rules when it reads the config, so
       // without this banner the path would just stop routing with no

From 3271555abf22aca496f6f395b1d2f17627314b61 Mon Sep 17 00:00:00 2001
From: Buck Doyle <buck.doyle@cardstack.com>
Date: Tue, 4 Aug 2026 09:06:01 -0500
Subject: [PATCH 10/12] Drop the dead radio group name from the routing rule
 editor

RadioInput takes the group name as @name and falls back to naming the
group after itself; a bare name= attribute lands on the fieldset through
...attributes, where it does nothing for grouping. So the counter and
the field feeding it never reached an input. The guid fallback already
gives each rule its own group, which is the behavior in place today.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/base/realm-config.gts | 7 ++-----
 1 file changed, 2 insertions(+), 5 deletions(-)

diff --git a/packages/base/realm-config.gts b/packages/base/realm-config.gts
index a1e9c1aae80..63342054508 100644
--- a/packages/base/realm-config.gts
+++ b/packages/base/realm-config.gts
@@ -72,16 +72,12 @@ class RoutingRuleAtom extends Component<typeof RoutingRuleField> {
   </template>
 }
 
-let routingRuleKindGroupNumber = 0;
-
 class RoutingRuleEdit extends Component<typeof RoutingRuleField> {
   private kindItems: { id: 'card' | 'redirect'; text: string }[] = [
     { id: 'card', text: 'Render a card' },
     { id: 'redirect', text: 'Redirect' },
   ];
 
-  private kindRadioGroup = `__routing_rule_kind${routingRuleKindGroupNumber++}__`;
-
   private statusCodeOptions = [...REDIRECT_STATUS_CODES];
 
   constructor(owner: Owner, args: any) {
@@ -205,10 +201,11 @@ class RoutingRuleEdit extends Component<typeof RoutingRuleField> {
   <template>
     <div class='routing-rule-edit' data-test-routing-rule-edit>
       <div class='kind-toggle' data-test-routing-rule-kind>
+        {{! RadioInput names the group after itself when @name is absent,
+            which is what keeps each rule's pair of radios independent. }}
         <RadioInput
           @items={{this.kindItems}}
           @groupDescription='Routing rule target'
-          name='{{this.kindRadioGroup}}'
           @checkedId={{this.kind}}
           @spacing='compact'
           @hideBorder={{true}}

From 750b4350f89f051db6b071505d051f8d0ed31445 Mon Sep 17 00:00:00 2001
From: Buck Doyle <buck.doyle@cardstack.com>
Date: Tue, 4 Aug 2026 09:13:16 -0500
Subject: [PATCH 11/12] Fall back to a routing rule's card when its redirect
 target is unusable
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A rule carrying both an instance and a malformed redirectTo was dropped
whole, so a path that had been serving a card started resolving as if
unrouted — the dead end the branch's own comment disclaims, and a
regression against the previous behavior of ignoring an unrecognized
redirectTo key. Only a hand-edited realm.json can produce the pairing,
since the editor clears one target when the other is chosen.

An unusable target now falls through to the instance instead of taking
the rule down with it. With no usable instance either, the rule still
drops. The log line says ignoring rather than dropping to match.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../realm-server/tests/realm-routing-test.ts  | 27 +++++++++++++++-
 packages/runtime-common/realm.ts              | 32 +++++++++++--------
 2 files changed, 45 insertions(+), 14 deletions(-)

diff --git a/packages/realm-server/tests/realm-routing-test.ts b/packages/realm-server/tests/realm-routing-test.ts
index 634c750c06d..4089891b13f 100644
--- a/packages/realm-server/tests/realm-routing-test.ts
+++ b/packages/realm-server/tests/realm-routing-test.ts
@@ -70,6 +70,10 @@ function makeRoutingFixture(): Record<
             { path: '/self', redirectTo: '/self' },
             { path: '/ring-a', redirectTo: '/ring-b' },
             { path: '/ring-b', redirectTo: '/ring-a' },
+            // An unusable redirect target on a rule that also has a
+            // card: the route keeps serving the card rather than going
+            // down with the typo.
+            { path: '/salvaged', redirectTo: 'terms' },
           ],
         },
         relationships: {
@@ -94,6 +98,11 @@ function makeRoutingFixture(): Record<
           'hostRoutingRules.6.instance': {
             links: { self: './white-paper' },
           },
+          // Also carries both, but the redirect target is malformed —
+          // the rule must fall back to serving this card.
+          'hostRoutingRules.10.instance': {
+            links: { self: './white-paper' },
+          },
         },
         meta: {
           adoptsFrom: {
@@ -139,8 +148,24 @@ module(basename(import.meta.filename), function () {
             statusCode: 301,
           },
           { path: '/ambiguous', redirectTo: '/elsewhere', statusCode: 302 },
+          { path: '/salvaged', id: `${realmURL.href}white-paper` },
         ],
-        'relative reference resolved against the realm root; cross-realm rule filtered; trailing-slash rule normalized to /trailing; redirect rules surface with their (default) status; the invalid javascript: target is dropped; a rule with both targets resolves as a redirect; self-redirect and ring rules dropped',
+        'relative reference resolved against the realm root; cross-realm rule filtered; trailing-slash rule normalized to /trailing; redirect rules surface with their (default) status; the invalid javascript: target is dropped; a rule with both targets resolves as a redirect; self-redirect and ring rules dropped; a rule whose redirect target is malformed falls back to its card',
+      );
+    });
+
+    test('an unusable redirect target falls back to the rule’s card instead of dropping the route', async function (assert) {
+      let map = await testRealm.getHostRoutingMap();
+
+      assert.deepEqual(
+        map.find((rule) => rule.path === '/salvaged'),
+        { path: '/salvaged', id: `${realmURL.href}white-paper` },
+        'the route still serves its card despite the malformed redirect target',
+      );
+      assert.strictEqual(
+        map.find((rule) => rule.path === '/bad-redirect'),
+        undefined,
+        'with no card to fall back to, the rule is dropped',
       );
     });
 
diff --git a/packages/runtime-common/realm.ts b/packages/runtime-common/realm.ts
index f3a673e06e8..350ad8aec56 100644
--- a/packages/runtime-common/realm.ts
+++ b/packages/runtime-common/realm.ts
@@ -6877,26 +6877,32 @@ export class Realm {
         let normalizedPath = normalizeRoutingPath(path);
         let redirectTo = (rule as Record<string, unknown>).redirectTo;
         if (typeof redirectTo === 'string' && redirectTo.trim()) {
-          // A redirect rule. When a rule carries both `redirectTo` and
-          // `instance` (only possible by hand-editing realm.json — the
-          // editor clears one when the other is chosen), the redirect
-          // wins: it is the more explicit declaration, and silently
-          // dropping the rule would dead-end the path.
+          // A redirect rule. A rule carrying both `redirectTo` and
+          // `instance` is only reachable by hand-editing realm.json —
+          // the editor clears one when the other is chosen — and the
+          // redirect wins as the more explicit declaration.
+          //
+          // Unless it doesn't hold up: an unusable target falls through
+          // to the instance below rather than taking the rule down with
+          // it, so a typo in a hand-added `redirectTo` leaves a route
+          // that was serving a card still serving it. With no usable
+          // instance either, the rule drops and the path resolves as if
+          // unrouted.
           let target = redirectTo.trim();
           let warning = validateRedirectTarget(target);
           if (warning) {
             this.#log.warn(
-              `dropping host routing rule for path "${normalizedPath}" — invalid redirect target ${JSON.stringify(
+              `ignoring invalid redirect target ${JSON.stringify(
                 target,
-              )}: ${warning}`,
+              )} on host routing rule for path "${normalizedPath}": ${warning}`,
             );
-            return [];
+          } else {
+            let statusCode =
+              parseRedirectStatusCode(
+                (rule as Record<string, unknown>).statusCode,
+              ) ?? DEFAULT_REDIRECT_STATUS;
+            return [{ path: normalizedPath, redirectTo: target, statusCode }];
           }
-          let statusCode =
-            parseRedirectStatusCode(
-              (rule as Record<string, unknown>).statusCode,
-            ) ?? DEFAULT_REDIRECT_STATUS;
-          return [{ path: normalizedPath, redirectTo: target, statusCode }];
         }
         if (!instance || typeof instance !== 'object') return [];
         let id = (instance as Record<string, unknown>).id;

From 2d4d8643dc96688f6327804c6711a16b7d9574b5 Mon Sep 17 00:00:00 2001
From: Buck Doyle <buck.doyle@cardstack.com>
Date: Tue, 4 Aug 2026 09:26:22 -0500
Subject: [PATCH 12/12] Resolve redirect targets through one shared helper
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The server worked the target out twice — once for the Location header,
once for the routing map it injects for the SPA — from two copies of the
same expression. Editing one would have sent a full-page visitor and an
in-app one to different places. resolveRedirectTarget now backs both,
with isExternalRedirectTarget shared by the SPA's own resolution.

The SPA also re-declared the rule union locally, widening statusCode to
number, and discriminated on a raw 'redirectTo' in check. Both now use
HostRoutingRule and isRedirectRoutingRule, so the shape and its
discriminant are declared once.

No behavior change: the helper reproduces both former expressions for
external, relative, multi-slash, query-bearing and root-mounted targets.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 packages/host/app/routes/index.gts            |  7 ++-
 .../host/app/services/host-mode-service.ts    | 23 ++++----
 .../host/tests/acceptance/host-mode-test.gts  |  4 +-
 packages/realm-server/handlers/serve-index.ts | 47 ++++++++-------
 .../tests/host-routing-validation-test.ts     | 18 ++++++
 .../runtime-common/host-routing-validation.ts | 37 ++++++++++++
 .../tests/host-routing-validation-test.ts     | 57 +++++++++++++++++++
 7 files changed, 152 insertions(+), 41 deletions(-)

diff --git a/packages/host/app/routes/index.gts b/packages/host/app/routes/index.gts
index 45e78d380b3..579ed96fc38 100644
--- a/packages/host/app/routes/index.gts
+++ b/packages/host/app/routes/index.gts
@@ -8,7 +8,10 @@ import { isTesting } from '@embroider/macros';
 import window from 'ember-window-mock';
 import stringify from 'safe-stable-stringify';
 
-import { HOST_APP_QUERY_PARAMS } from '@cardstack/runtime-common';
+import {
+  HOST_APP_QUERY_PARAMS,
+  isRedirectRoutingRule,
+} from '@cardstack/runtime-common';
 import { isFileDefInstance } from '@cardstack/runtime-common/code-ref';
 
 import { Submodes } from '@cardstack/host/components/submode-switcher';
@@ -98,7 +101,7 @@ export default class Card extends Route {
       let routed = this.hostModeService.resolveRoutedPath(
         normalizedPath || '/',
       );
-      if (routed && 'redirectTo' in routed) {
+      if (routed && isRedirectRoutingRule(routed)) {
         this.hostModeService.redirectTo(
           routed.redirectTo,
           this.forwardableQueryParams(transition),
diff --git a/packages/host/app/services/host-mode-service.ts b/packages/host/app/services/host-mode-service.ts
index 49d3c8bab65..dfabeac93bd 100644
--- a/packages/host/app/services/host-mode-service.ts
+++ b/packages/host/app/services/host-mode-service.ts
@@ -5,8 +5,10 @@ import { tracked } from '@glimmer/tracking';
 import window from 'ember-window-mock';
 
 import {
+  isExternalRedirectTarget,
   normalizeRoutingPath,
   sanitizeHeadHTML,
+  type HostRoutingRule,
 } from '@cardstack/runtime-common';
 
 import config from '@cardstack/host/config/environment';
@@ -35,14 +37,6 @@ interface PublishedRealmMetadata {
   currentCardUrlString: string | undefined;
 }
 
-// The host-scoped form of a routing rule as the realm-server injects it
-// into the config meta tag: every path (and any realm-relative redirect
-// target) is already prefixed with the realm's mount pathname, so a
-// redirect target can be handed straight to a location change.
-export type HostScopedRoutingRule =
-  | { path: string; id: string }
-  | { path: string; redirectTo: string; statusCode: number };
-
 export default class HostModeService extends Service {
   @service declare hostModeStateService: HostModeStateService;
   @service declare operatorModeStateService: OperatorModeStateService;
@@ -130,10 +124,13 @@ export default class HostModeService extends Service {
   // per-request when the request hits a realm whose config card has
   // hostRoutingRules — so the first-render decision in the index route
   // is synchronous and the field is part of the typed config surface
-  // rather than a window global.
-  get hostRoutingMap(): HostScopedRoutingRule[] {
+  // rather than a window global. The rules arrive host-scoped — every
+  // path, and any realm-relative redirect target, already carries the
+  // realm's mount pathname — so a target can go straight to a location
+  // change without the SPA knowing where the realm is mounted.
+  get hostRoutingMap(): HostRoutingRule[] {
     let map = (config as { hostRoutingMap?: unknown }).hostRoutingMap;
-    return Array.isArray(map) ? (map as HostScopedRoutingRule[]) : [];
+    return Array.isArray(map) ? (map as HostRoutingRule[]) : [];
   }
 
   // Returns the routing rule matching `path`, else null. A serve rule
@@ -154,7 +151,7 @@ export default class HostModeService extends Service {
   // trailing slashes, preserves the root `/`) before comparing, so
   // `/realm` ↔ `/realm/` resolve and the client agrees with how the server
   // map builder and the editor normalize.
-  resolveRoutedPath(path: string): HostScopedRoutingRule | null {
+  resolveRoutedPath(path: string): HostRoutingRule | null {
     let normalized = path.startsWith('/') ? path : `/${path}`;
     let canonical = normalizeRoutingPath(normalized);
     let rule = this.hostRoutingMap.find(
@@ -187,7 +184,7 @@ export default class HostModeService extends Service {
   // host mode anyway; only the simulation affordance separates them,
   // and a simulated session should stay on the page it is running from.
   redirectTo(target: string, queryParams?: Record<string, unknown>) {
-    let url = /^https?:/i.test(target)
+    let url = isExternalRedirectTarget(target)
       ? new URL(target)
       : new URL(target, window.location.origin);
     if (!url.search && queryParams) {
diff --git a/packages/host/tests/acceptance/host-mode-test.gts b/packages/host/tests/acceptance/host-mode-test.gts
index 467da2b8399..9bfb1c724c2 100644
--- a/packages/host/tests/acceptance/host-mode-test.gts
+++ b/packages/host/tests/acceptance/host-mode-test.gts
@@ -12,7 +12,7 @@ import { getPageTitle } from 'ember-page-title/test-support';
 import window from 'ember-window-mock';
 import { module, test } from 'qunit';
 
-import { Deferred } from '@cardstack/runtime-common';
+import { Deferred, type HostRoutingRule } from '@cardstack/runtime-common';
 
 import HostModeService from '@cardstack/host/services/host-mode-service';
 import type StoreService from '@cardstack/host/services/store';
@@ -61,7 +61,7 @@ class StubCustomSubdomainHostModeService extends StubHostModeService {
 // which is `/test/` as this app sees it (`hostModeOrigin` absorbs the
 // `/user` segment above).
 class StubRoutingHostModeService extends StubHostModeService {
-  get hostRoutingMap() {
+  get hostRoutingMap(): HostRoutingRule[] {
     return [
       { path: '/test/terms', id: `${testHostModeRealmURL}Pet/mango` },
       { path: '/test/tos', redirectTo: '/test/terms', statusCode: 302 },
diff --git a/packages/realm-server/handlers/serve-index.ts b/packages/realm-server/handlers/serve-index.ts
index 0268334396d..8090b4198eb 100644
--- a/packages/realm-server/handlers/serve-index.ts
+++ b/packages/realm-server/handlers/serve-index.ts
@@ -13,6 +13,7 @@ import {
   logger,
   param,
   query,
+  resolveRedirectTarget,
   sanitizeHeadHTMLToString,
 } from '@cardstack/runtime-common';
 import type { MatrixClient } from '@cardstack/runtime-common/matrix-client';
@@ -404,27 +405,23 @@ export function createServeIndex(deps: ServeIndexDeps): ServeIndexHandlers {
           // A declared redirect rule. Redirect straight to the
           // declared target from either trailing-slash form of the
           // matched path — canonicalizing first would cost the client a
-          // second hop for no benefit. A realm-relative target resolves
-          // against the realm's mount pathname, mirroring how the
-          // rule's own `path` is mounted; extra leading slashes are
-          // collapsed so a target can never be read as protocol-
-          // relative. The request's query string carries over unless
-          // the target declares its own — minus the host app's own
-          // params, which a redirect has no business handing on: the
-          // target may be an external site, and `sid` / `clientSecret`
-          // are password-reset tokens. The SPA drops the same list on
-          // its in-app navigation, so both answer the same URL.
+          // second hop for no benefit. `resolveRedirectTarget` is shared
+          // with the routing map injected further down, so the URL a
+          // full-page visitor is sent to and the one an in-app
+          // transition resolves cannot drift apart. The request's query
+          // string carries over unless the target declares its own —
+          // minus the host app's own params, which a redirect has no
+          // business handing on: the target may be an external site, and
+          // `sid` / `clientSecret` are password-reset tokens. The SPA
+          // drops the same list on its in-app navigation.
           let { redirectTo, statusCode } = matched.rule;
-          let target: URL;
-          if (/^https?:/i.test(redirectTo)) {
-            target = new URL(redirectTo);
-          } else {
-            let realmPathname = new URL(matched.realm.url).pathname;
-            target = new URL(
-              realmPathname + redirectTo.replace(/^\/+/, ''),
-              requestURL,
-            );
-          }
+          let target = new URL(
+            resolveRedirectTarget(
+              redirectTo,
+              new URL(matched.realm.url).pathname,
+            ),
+            requestURL,
+          );
           if (requestURL.search && !target.search) {
             let forwarded = foreignQueryParams(requestURL.search);
             if (forwarded) {
@@ -564,10 +561,12 @@ export function createServeIndex(deps: ServeIndexDeps): ServeIndexHandlers {
           // A redirect rule's realm-relative target is prefixed the same
           // way as its path, so the SPA can hand the value straight to a
           // location change without knowing the realm's mount point.
-          let redirectTo = /^https?:/i.test(rule.redirectTo)
-            ? rule.redirectTo
-            : realmPathname + rule.redirectTo.replace(/^\/+/, '');
-          return { path, redirectTo, statusCode: rule.statusCode };
+          // Same helper the `Location` header above goes through.
+          return {
+            path,
+            redirectTo: resolveRedirectTarget(rule.redirectTo, realmPathname),
+            statusCode: rule.statusCode,
+          };
         }
         return { path, id: rule.id };
       });
diff --git a/packages/realm-server/tests/host-routing-validation-test.ts b/packages/realm-server/tests/host-routing-validation-test.ts
index 4314b3d01ed..ece4685d520 100644
--- a/packages/realm-server/tests/host-routing-validation-test.ts
+++ b/packages/realm-server/tests/host-routing-validation-test.ts
@@ -131,6 +131,24 @@ module(basename(import.meta.filename), function () {
     });
   });
 
+  module('resolveRedirectTarget', function () {
+    test('resolveRedirectTarget: prefixes a realm-relative target with the mount pathname', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+
+    test('resolveRedirectTarget: hands back an external target untouched', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+
+    test('resolveRedirectTarget: collapses every leading slash', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+
+    test('isExternalRedirectTarget: distinguishes http(s) targets from realm paths', async function (assert) {
+      await runSharedTest(hostRoutingValidationTests, assert, {});
+    });
+  });
+
   module('foreignQueryParams', function () {
     test('foreignQueryParams: keeps params the host app does not own', async function (assert) {
       await runSharedTest(hostRoutingValidationTests, assert, {});
diff --git a/packages/runtime-common/host-routing-validation.ts b/packages/runtime-common/host-routing-validation.ts
index baa3d003844..6ad42fe0a90 100644
--- a/packages/runtime-common/host-routing-validation.ts
+++ b/packages/runtime-common/host-routing-validation.ts
@@ -82,6 +82,43 @@ export function isRedirectRoutingRule(
   return 'redirectTo' in rule;
 }
 
+const EXTERNAL_TARGET_PATTERN = /^https?:/i;
+
+/**
+ * Whether a redirect target leaves the realm. External targets are used
+ * verbatim; everything else is a path within the realm.
+ */
+export function isExternalRedirectTarget(target: string): boolean {
+  return EXTERNAL_TARGET_PATTERN.test(target);
+}
+
+/**
+ * The host-scoped form of a redirect target: what the browser should end
+ * up at, expressed the way the realm is actually mounted. An external
+ * target is handed back untouched; a realm-relative one is joined onto
+ * `realmPathname` (which ends in `/`), the same prefixing a rule's own
+ * `path` gets, so `/terms` under a realm mounted at `/sick-elk/` becomes
+ * `/sick-elk/terms`.
+ *
+ * Every leading slash is collapsed, not just the first, so the result
+ * can never start `//` and be read as protocol-relative. Malformed
+ * targets are already dropped when the routing map is built; this is the
+ * backstop.
+ *
+ * Shared because the server needs this twice — once for the `Location`
+ * header it answers, once for the routing map it injects for the SPA —
+ * and the two answering different URLs would send a full-page visitor
+ * and an in-app one to different places.
+ */
+export function resolveRedirectTarget(
+  redirectTo: string,
+  realmPathname: string,
+): string {
+  return isExternalRedirectTarget(redirectTo)
+    ? redirectTo
+    : `${realmPathname}${redirectTo.replace(/^\/+/, '')}`;
+}
+
 /**
  * Canonical form of a routing rule path: a trailing slash is stripped so
  * `/pricing/` and `/pricing` compare and match identically, with the realm
diff --git a/packages/runtime-common/tests/host-routing-validation-test.ts b/packages/runtime-common/tests/host-routing-validation-test.ts
index 050e7a343df..9c10e28c391 100644
--- a/packages/runtime-common/tests/host-routing-validation-test.ts
+++ b/packages/runtime-common/tests/host-routing-validation-test.ts
@@ -2,8 +2,10 @@ import {
   findDuplicateRoutingPaths,
   findRedirectCycles,
   foreignQueryParams,
+  isExternalRedirectTarget,
   normalizeRoutingPath,
   parseRedirectStatusCode,
+  resolveRedirectTarget,
   validateRedirectTarget,
   validateRoutingPath,
 } from '../host-routing-validation.ts';
@@ -388,6 +390,61 @@ const tests: SharedTests<unknown> = Object.freeze({
     );
   },
 
+  'resolveRedirectTarget: prefixes a realm-relative target with the mount pathname':
+    async (assert) => {
+      assert.strictEqual(
+        resolveRedirectTarget('/terms', '/sick-elk/'),
+        '/sick-elk/terms',
+      );
+      assert.strictEqual(
+        resolveRedirectTarget('/legal/terms?v=2', '/sick-elk/'),
+        '/sick-elk/legal/terms?v=2',
+        'a query on the target is carried along untouched',
+      );
+      assert.strictEqual(
+        resolveRedirectTarget('/terms', '/'),
+        '/terms',
+        'a realm mounted at the root adds nothing',
+      );
+    },
+
+  'resolveRedirectTarget: hands back an external target untouched': async (
+    assert,
+  ) => {
+    assert.strictEqual(
+      resolveRedirectTarget('https://example.com/landing', '/sick-elk/'),
+      'https://example.com/landing',
+    );
+    assert.strictEqual(
+      resolveRedirectTarget('HTTPS://example.com/x', '/sick-elk/'),
+      'HTTPS://example.com/x',
+      'the scheme test is case-insensitive',
+    );
+  },
+
+  'resolveRedirectTarget: collapses every leading slash': async (assert) => {
+    // Malformed targets are dropped when the map is built; this is the
+    // backstop that keeps the result from starting `//` and reading as
+    // protocol-relative.
+    assert.strictEqual(
+      resolveRedirectTarget('//example.com/x', '/sick-elk/'),
+      '/sick-elk/example.com/x',
+    );
+    assert.strictEqual(
+      resolveRedirectTarget('///terms', '/sick-elk/'),
+      '/sick-elk/terms',
+    );
+  },
+
+  'isExternalRedirectTarget: distinguishes http(s) targets from realm paths':
+    async (assert) => {
+      assert.true(isExternalRedirectTarget('https://example.com'));
+      assert.true(isExternalRedirectTarget('http://example.com'));
+      assert.true(isExternalRedirectTarget('HtTpS://example.com'));
+      assert.false(isExternalRedirectTarget('/terms'));
+      assert.false(isExternalRedirectTarget('//example.com'));
+    },
+
   'foreignQueryParams: keeps params the host app does not own': async (
     assert,
   ) => {