.changeset/yellow-vans-walk.md (1)

5-5: Hyphenate “cross‑origin” and clarify scope.

Nit: use “cross-origin” and call out document navigations to better reflect the code path gated by sec-fetch-dest === 'document'.

-Fix logic for forcing a session sync on cross origin requests.
+Fix logic for forcing a session sync on cross-origin document requests from non‑Clerk domains.

packages/backend/src/tokens/request.ts (1)

576-587: Name the reason string or reuse a constant to ease log-based triage.

Optional: the literal message 'Cross-origin request from satellite domain requires handshake' could be extracted to a constant near AuthErrorReason.PrimaryDomainCrossOriginSync for consistency and easier grep.

- 'Cross-origin request from satellite domain requires handshake',
+ HANDSHAKE_MESSAGES.PrimaryDomainCrossOriginSync,

Supporting snippet (outside this hunk):

export const HANDSHAKE_MESSAGES = {
  PrimaryDomainCrossOriginSync: 'Cross-origin request from satellite domain requires handshake',
} as const;

packages/backend/src/tokens/__tests__/request.test.ts (1)

1640-1665: Dev accounts portal (current) coverage looks good. Consider adding accountsstage.

Optional: add a staging variant (e.g., accountsstage.<...>) to mirror buildAccountsBaseUrl handling and ensure parity across environments.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

packages/backend/src/tokens/request.ts (1)

576-583: Correctly exempts Clerk-origin referers from cross-origin handshake.

The additional checks against isCrossOriginReferrer() and !authenticateContext.isClerkDomain() align the handshake trigger with intended flows from Clerk-hosted UIs. Looks good.

packages/backend/src/tokens/authenticateContext.ts (1)

1-2: Imports are appropriate and scoped.

buildAccountsBaseUrl and the dev accounts portal origin helpers are used only by the new referrer classifier. No issues.

packages/backend/src/tokens/__tests__/request.test.ts (1)

1710-1744: Good coverage for FAPI referers (redirect-based auth).

The cases for clerk.<...>/v1/... and https://clerk.<...>/sign-in correctly assert that we do not trigger PrimaryDomainCrossOriginSync. Nice.

.changeset/yellow-vans-walk.md (1)

5-5: Tighten wording and fix hyphenation in the changeset summary

Recommend using “cross-origin” and clarifying what changed to aid release notes skimming.

Apply:

-Fix logic for forcing a session sync on cross origin requests.
+Fix primary-domain cross-origin handshake logic by skipping the forced session sync when the referrer is a Clerk-owned domain (accounts.* or FAPI).

packages/backend/src/tokens/__tests__/request.test.ts (1)

1696-1769: Strengthen assertions to ensure we remain signed in (not just “not PrimaryDomainCrossOriginSync”)

A few tests only assert that the reason is not PrimaryDomainCrossOriginSync. This could pass even if a different handshake was triggered (e.g., DevBrowserMissing on test instances). Prefer asserting SignedIn when feasible.

Example tweak:

-      // Should not trigger the specific cross-origin sync handshake we're trying to prevent
-      expect(requestState.reason).not.toBe(AuthErrorReason.PrimaryDomainCrossOriginSync);
+      // Should remain signed in (no cross-origin sync handshake)
+      expect(requestState).toBeSignedIn({
+        domain: 'primary.com',
+        isSatellite: false,
+        signInUrl: 'https://primary.com/sign-in',
+      });

If you need to avoid dev-browser handshakes, either:

• use publishableKey: PK_LIVE for those cases, or
• include a dev browser token in cookies (__clerk_db_jwt) to satisfy the development precondition.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

packages/backend/src/tokens/request.ts (1)

575-581: Correct guard: avoid cross-origin handshake when coming from Clerk-owned referrers

The added !authenticateContext.isClerkDomain() check is the right constraint to prevent unnecessary handshakes when the navigation originated from Clerk-hosted UIs or FAPI. Logic order and predicates look good with the existing sec-fetch-dest === 'document' gate.

If you want to be extra safe, add one regression test to assert no handshake when:

• primary domain request
• referer = FAPI host for a proxied instance (PK with proxyUrl),
• sec-fetch-site: cross-site,
• sec-fetch-dest: document.

packages/backend/src/tokens/authenticateContext.ts (1)

1-2: New shared imports: confirm tree-shaking and side-effect-free modules

These imports look correct and align with how shared helpers are split. Just ensure @clerk/shared/url exports are side-effect free to keep backend bundle lean.

If size matters for your target, run a quick bundle-size check or confirm these modules don’t pull browser-only code.

packages/backend/src/tokens/__tests__/request.test.ts (2)

1609-1666: Good coverage: production and dev Accounts portals (current/legacy) skip handshake

These tests validate the intended behavior well for accounts.* origins. Nice.

---

1769-1798: Add a proxy-aware test case

Please add a case where the PK is proxied (set proxyUrl) and the referer is:

• the unproxied FAPI host, and
• the derived Accounts origin from that unproxied FAPI.

Both should not trigger the cross-origin sync handshake if you adopt the originalFrontendApi fix.

You can base it on the existing tests; set mockOptions({ proxyUrl: 'https://edge.acme.dev' }) and keep PK pointing to a test instance so the unproxied FAPI/Accounts are predictable from the PK.

packages/backend/src/tokens/__tests__/request.test.ts (2)

1609-1636: Avoid relying on permissive accounts.* fallback in this test; bind to the instance’s real accounts origin or make intent explicit.

This case passes only because production code currently treats any accounts.* host as a Clerk domain. That makes the test brittle and potentially masks over-broad matching. Prefer asserting with the PK-derived accounts origin used in this test suite (or clearly label this as a fallback behavior test).

Two options:

Option A (preferred): use the PK-derived accounts origin to decouple from the global accounts.* fallback.

-    test('does not trigger handshake when referer is from production accounts portal', async () => {
+    test('does not trigger handshake when referer is from the instance accounts portal (derived from PK)', async () => {
@@
-          referer: 'https://accounts.example.com/sign-in',
+          referer: 'https://accounts.inspired.puma-74.lcl.dev/sign-in',
@@
-        publishableKey: PK_LIVE,
+        // Keep the publishable key aligned with the derived dev host above
+        publishableKey: PK_TEST,

Option B: if you intentionally want to document the permissive behavior, rename the test to make that explicit.

-    test('does not trigger handshake when referer is from production accounts portal', async () => {
+    test('does not trigger handshake when referer is an accounts.* fallback domain (documents current behavior)', async () => {

Would you like me to follow through and propagate Option A across the suite, replacing any remaining fallback-shaped cases with PK-derived hosts?

---

1609-1830: Add a negative test for unrelated accounts.* domains (if you plan to tighten matching).

To prevent over-broad whitelisting, add a case where the referer is an unrelated accounts.* domain and assert that PrimaryDomainCrossOriginSync is triggered. This will fail today if production intentionally treats any accounts.* as a Clerk domain; keep it for a follow-up when isClerkDomain is tightened, or mark it todo until then.

@@   describe('Cross-origin sync', () => {
+    test('triggers handshake when referer is unrelated accounts.* domain', async () => {
+      const request = mockRequestWithCookies(
+        {
+          referer: 'https://accounts.attacker.com/sign-in',
+          'sec-fetch-dest': 'document',
+          'sec-fetch-site': 'cross-site',
+        },
+        {
+          __session: mockJwt,
+          __client_uat: '12345',
+        },
+        'https://primary.com/dashboard',
+      );
+
+      const requestState = await authenticateRequest(request, {
+        ...mockOptions(),
+        publishableKey: PK_LIVE,
+        domain: 'primary.com',
+        isSatellite: false,
+        signInUrl: 'https://primary.com/sign-in',
+      });
+
+      expect(requestState).toMatchHandshake({
+        reason: AuthErrorReason.PrimaryDomainCrossOriginSync,
+        domain: 'primary.com',
+        signInUrl: 'https://primary.com/sign-in',
+      });
+    });

If you want, I can open a follow-up to scope isClerkDomain() to PK-derived hosts + vetted allowlist and land this test together with that change.

packages/backend/src/tokens/__tests__/request.test.ts (4)

1717-1719: Strengthen the assertion: assert positive SignedIn state rather than “not a specific reason”.

Checking only that the reason is not PrimaryDomainCrossOriginSync could pass even if another handshake reason fires. Assert the successful path.

-      // Should not trigger the specific cross-origin sync handshake we're trying to prevent
-      expect(requestState.reason).not.toBe(AuthErrorReason.PrimaryDomainCrossOriginSync);
+      expect(requestState).toBeSignedIn({
+        domain: 'primary.com',
+        isSatellite: false,
+        signInUrl: 'https://primary.com/sign-in',
+      });
+      expect(requestState.toAuth()).toBeSignedInToAuth();

---

1721-1744: Apply the same stronger assertion pattern here (FAPI – redirect-based auth).

Ensure we validate the intended SignedIn outcome, not just absence of one specific reason.

-      // Should not trigger the specific cross-origin sync handshake we're trying to prevent
-      expect(requestState.reason).not.toBe(AuthErrorReason.PrimaryDomainCrossOriginSync);
+      expect(requestState).toBeSignedIn({
+        domain: 'primary.com',
+        isSatellite: false,
+        signInUrl: 'https://primary.com/sign-in',
+      });
+      expect(requestState.toAuth()).toBeSignedInToAuth();

---

1746-1769: Same here: assert SignedIn result for FAPI “https prefix” variant.

-      // Should not trigger the specific cross-origin sync handshake we're trying to prevent
-      expect(requestState.reason).not.toBe(AuthErrorReason.PrimaryDomainCrossOriginSync);
+      expect(requestState).toBeSignedIn({
+        domain: 'primary.com',
+        isSatellite: false,
+        signInUrl: 'https://primary.com/sign-in',
+      });
+      expect(requestState.toAuth()).toBeSignedInToAuth();

---

1609-1830: Reduce duplication with a small helper for “primary doc request with cookies”.

Many tests clone the same inputs (cookies, target URL, options). A tiny factory improves readability and maintenance:

// Place near other test helpers
const buildPrimaryDocRequest = (referer: string, extraHeaders: Record<string, string> = {}) =>
  mockRequestWithCookies(
    { referer, 'sec-fetch-dest': 'document', ...extraHeaders },
    { __session: mockJwt, __client_uat: '12345' },
    'https://primary.com/dashboard',
  );

const primaryOptions = () =>
  mockOptions({
    publishableKey: PK_LIVE,
    domain: 'primary.com',
    isSatellite: false,
    signInUrl: 'https://primary.com/sign-in',
  });

// Usage in tests:
// const request = buildPrimaryDocRequest('https://accounts.inspired.puma-74.lcl.dev/sign-in', { 'sec-fetch-site': 'cross-site' });
// const requestState = await authenticateRequest(request, primaryOptions());

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

packages/backend/src/tokens/__tests__/request.test.ts (3)

1638-1694: LGTM: solid coverage for dev accounts portals (current and legacy).

These two tests exercise both foo-bar-13.accounts.dev and accounts.foo-bar-13.lcl.dev patterns and correctly assert no handshake.

---

1771-1798: LGTM: verifies handshake still fires for non-accounts cross-origin referers.

Good guardrail ensuring we didn’t suppress legitimate cross-origin syncs.

---

1800-1829: LGTM: covers redirect-chain quirk with sec-fetch-site: cross-site but same-origin referrer.

Nice edge case; prevents accidental over-triggering of handshakes.

packages/backend/src/tokens/__tests__/request.test.ts (3)

1634-1662: Avoid relying on permissive “accounts.*” fallback; use a PK-derived accounts origin (or parameterize).

This test passes today because production code accepts any “accounts.*” host. If matching is tightened later, it could fail. Prefer using the accounts origin derived from the publishable key used in these tests (same host you use elsewhere), or parameterize against a helper.

Minimal change (align with the PK-derived host already used elsewhere in this file):

-    test('does not trigger handshake when referer is from production accounts portal', async () => {
+    test('does not trigger handshake when referer is from accounts portal derived from PK', async () => {
@@
-          referer: 'https://accounts.example.com/sign-in',
+          referer: 'https://accounts.inspired.puma-74.lcl.dev/sign-in',

Alternative: derive the referer from the same source the app uses (e.g., buildAccountsBaseUrl(frontendApi) seeded by the PK) to remove hardcoding altogether. I can help wire that into the test if you prefer.

---

1692-1719: Same as previous: fold legacy/current dev portal cases into one parameterized test.

This block can be consolidated with the one above to avoid duplication and ease adding new domains in the future.

---

1796-1823: Add a negative test: “accounts.attacker.com” must still trigger handshake.

To guard against over-broad whitelisting of accounts.* domains, add a case where the referer is an unrelated accounts.* host and assert PrimaryDomainCrossOriginSync is triggered.

@@
     test('still triggers handshake for legitimate cross-origin requests from non-accounts domains', async () => {
@@
     });
+
+    test('triggers handshake when referer is unrelated accounts.* domain', async () => {
+      const request = mockRequestWithCookies(
+        {
+          referer: 'https://accounts.attacker.com/sign-in',
+          'sec-fetch-dest': 'document',
+          'sec-fetch-site': 'cross-site',
+        },
+        {
+          __session: mockJwt,
+          __client_uat: '12345',
+        },
+        'https://primary.com/dashboard',
+      );
+
+      const requestState = await authenticateRequest(request, {
+        ...mockOptions(),
+        publishableKey: PK_LIVE,
+        domain: 'primary.com',
+        isSatellite: false,
+        signInUrl: 'https://primary.com/sign-in',
+      });
+
+      expect(requestState).toMatchHandshake({
+        reason: AuthErrorReason.PrimaryDomainCrossOriginSync,
+        domain: 'primary.com',
+        signInUrl: 'https://primary.com/sign-in',
+      });
+    });

packages/backend/src/tokens/__tests__/request.test.ts (5)

1523-1546: Rename duplicate test title and also assert toAuth for stronger coverage.

There is already a prior test named “does not trigger handshake when referer is same origin.” Rename this one to avoid duplicate names and add a toAuth assertion so we also validate the auth payload is populated.

-    test('does not trigger handshake when referer is same origin', async () => {
+    test('does not trigger handshake when referer is same origin (localhost dev)', async () => {
@@
       expect(requestState).toBeSignedIn({
         signInUrl: 'http://localhost:3000/sign-in',
       });
+      expect(requestState.toAuth()).toBeSignedInToAuth();
     });

---

1663-1691: Reduce duplication with a table-driven test for dev accounts portal variants.

These two dev-accounts cases are nearly identical and can be collapsed into it.each for readability and future maintainability.

Example:

it.each([
  { name: 'current format', ref: 'https://foo-bar-13.accounts.dev/sign-in' },
  { name: 'legacy format', ref: 'https://accounts.foo-bar-13.lcl.dev/sign-in' },
])('does not trigger handshake when referer is from dev accounts portal (%s)', async ({ name, ref }) => {
  const request = mockRequestWithCookies(
    { referer: ref, 'sec-fetch-dest': 'document', 'sec-fetch-site': 'cross-site' },
    { __session: mockJwt, __client_uat: '12345' },
    'https://primary.com/dashboard',
  );
  const requestState = await authenticateRequest(request, {
    ...mockOptions(),
    publishableKey: PK_LIVE,
    domain: 'primary.com',
    isSatellite: false,
    signInUrl: 'https://primary.com/sign-in',
  });
  expect(requestState).toBeSignedIn({
    domain: 'primary.com',
    isSatellite: false,
    signInUrl: 'https://primary.com/sign-in',
  });
});

---

1721-1744: Strengthen the assertion: verify we’re actually signed in (not just “not this specific handshake”).

Only asserting that the reason is not PrimaryDomainCrossOriginSync leaves room for other unexpected states. Also assert SignedIn and toAuth to make the intent explicit.

-      // Should not trigger the specific cross-origin sync handshake we're trying to prevent
-      expect(requestState.reason).not.toBe(AuthErrorReason.PrimaryDomainCrossOriginSync);
+      // Should not trigger cross-origin sync; request should be fully authenticated
+      expect(requestState).not.toMatchHandshake({ reason: AuthErrorReason.PrimaryDomainCrossOriginSync });
+      expect(requestState).toBeSignedIn();
+      expect(requestState.toAuth()).toBeSignedInToAuth();

---

1746-1769: Apply the same stronger assertion for FAPI referers.

Validate SignedIn and toAuth in addition to the negative handshake assertion.

-      // Should not trigger the specific cross-origin sync handshake we're trying to prevent
-      expect(requestState.reason).not.toBe(AuthErrorReason.PrimaryDomainCrossOriginSync);
+      expect(requestState).not.toMatchHandshake({ reason: AuthErrorReason.PrimaryDomainCrossOriginSync });
+      expect(requestState).toBeSignedIn();
+      expect(requestState.toAuth()).toBeSignedInToAuth();

---

1771-1794: Same strengthening: assert SignedIn + toAuth for the https-prefixed FAPI case.

-      // Should not trigger the specific cross-origin sync handshake we're trying to prevent
-      expect(requestState.reason).not.toBe(AuthErrorReason.PrimaryDomainCrossOriginSync);
+      expect(requestState).not.toMatchHandshake({ reason: AuthErrorReason.PrimaryDomainCrossOriginSync });
+      expect(requestState).toBeSignedIn();
+      expect(requestState.toAuth()).toBeSignedInToAuth();

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

💡 Knowledge Base configuration:

• MCP integration is disabled by default for public repositories
• Jira integration is disabled
• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

packages/backend/src/tokens/__tests__/request.test.ts (1)

1825-1854: Nice edge-case coverage: same-origin referrer despite sec-fetch-site=cross-site.

This captures the redirect-chain quirk well and protects against regressions in the gating logic.