feat(hexclave): PR 1 — wire compatibility layer (invisible)#1475
Open
BilalG1 wants to merge 29 commits into
Open
feat(hexclave): PR 1 — wire compatibility layer (invisible)#1475BilalG1 wants to merge 29 commits into
BilalG1 wants to merge 29 commits into
Conversation
Captures the v6 rebrand plan: dual-support strategy for wire identifiers (HTTP headers, cookies, JWT issuers, Bearer prefix, OAuth state), SDK alias re-exports, npm dual-publish via rewrite-then-republish, Swift split into separate StackAuth/Hexclave packages, env var taxonomy, verification matrix, and 2-PR rollout.
…n rebrand plan Addresses review gaps in the Hexclave rename plan: - Storage keys: add the missed localStorage keys `_STACK_AUTH.lastUsed`, `stack:session-replay:v1:*`, `__stack-dev-tool-state`, and `stack-devtool-trigger-position`, with per-key compat risk notes. - Query parameters: new Tier 0 category — `stack_response_mode`, the four `stack_cross_domain_*` handoff params, and `stack-init-id` are wire-compat-sensitive and were previously uncovered. - Custom DOM events: `stack-platform-change` / `stack-framework-change`. - Dev tool: dev-tool-core.ts is its own brand surface (storage keys, header-emit site, DOM identifiers, brand strings).
- Tier 1: internal-only symbols (SDK interfaces, StackAssertionError) renamed outright with no alias; user-facing symbols keep aliases - Tier 2: @hexclave/* starts at 1.0.0, lockstep versioning; add npm deprecate + runtime warn for old packages; drop @hexclave/init - Env vars: all categories dual-read (incl. operator/internal); NEXT_PUBLIC_STACK_PORT_PREFIX renamed outright - Emails: noreply moves to sent-with-hexclave.com sending domain - CHIPS test cookies out of scope (unused feature) - Rollout split into 3 PRs: invisible compat layer, visible rebrand, far-future fallback removal
- Add "PR 1 implementation guide" section resolving every open item with concrete file:line references and chosen approach per work-area - Correction: Bearer stackauth_ prefix is SDK-internal, never parsed by the backend (was wrongly listed as a backend wire identifier) - Request headers: normalize at the existing empty proxy.tsx:114 hook (no readDualHeader helper, no per-route schema edits) - Env vars: hybrid dual-read (central getEnvVariable transform + two client files + per-site tail) - Symbol.for: four symbols, not three; only one needs dual-attach - Query params: add the two nested cross-domain params
Grep confirms x-stack-auth has zero references in apps/backend and packages/stack-shared. It is produced by the deprecated getAuthHeaders()/ useAuthHeaders() SDK methods and consumed by the SDK tokenStore parser (client-app-impl.ts) — the Stack backend never parses it. Reframed from "backend read-only wire identifier" to "SDK-internal legacy identifier", corrected the false "no current writer" claim, and resolved the open verification item.
Adds Hexclave* aliases for the user-facing Stack* exports (apps, provider, handler, theme, useStackApp, config) in packages/template; codegen propagates them to the generated SDKs. Additive and non-breaking. PR 1 of the Hexclave rebrand (see RENAME-TO-HEXCLAVE.md, Tier 1).
…e.com issuers decodeAccessToken now builds allowed issuers for both api.stack-auth.com and api.hexclave.com so tokens issued under either host keep validating across the domain transition. Signing is unchanged (follows the configured API URL).
Backend and dashboard proxies normalize each x-hexclave-* request header onto its x-stack-* equivalent before routing/validation, and add the x-hexclave-* names to the CORS allowlists. Existing x-stack-* clients are unaffected.
Both tools register identical schema/behavior via a shared helper; ask_stack_auth keeps working unchanged.
…ernal renames
Completes the PR 1 wire/compat layer for the Hexclave rebrand:
- Env vars: central getEnvVariable HEXCLAVE_* prefix-transform (dual-read);
dashboard + template client env files dual-read; turbo.json globalEnv;
NEXT_PUBLIC_STACK_PORT_PREFIX renamed outright (incl. docker entrypoint).
- Config discovery: CLI/dashboard/backend prefer hexclave.config.ts, fall
back to stack.config.ts; CLI credentials path dual-read.
- Response headers: backend dual-emits x-hexclave-*; SDK reads new first.
- SDK request headers: interfaces + dashboard api-headers emit x-hexclave-*.
- Bearer prefix: SDK token parser accepts stackauth_ and hexclave_.
- Cookies: dual-write/dual-read auth, OAuth-state and low-risk cookies.
- Storage keys + query params dual-handled; cross-domain params dual-emit.
- Symbols: app-internals symbol dual-attached; 3 file-private symbols renamed.
- Internal-only symbols renamed outright (no alias): StackAssertionError,
Stack{Client,Server,Admin}Interface.
Verified: pnpm typecheck and pnpm lint pass (pre-existing fresh-worktree
codegen gaps in stack-docs aside). e2e snapshot regeneration pending a CI run.
… emit Dev-tool root element id, global instance key, and trigger data-attribute renamed to hexclave-*; its hand-written fetch now emits X-Hexclave-* headers; window.HexclaveDevTool exposed alongside window.StackDevTool.
Four parallel review agents audited the PR 1 changes. Bugs found and fixed:
- snapshot-serializer.ts: keyedCookieNamePrefixes was interpolated as a
whole array (`${array}`) — adding a 2nd prefix corrupted ALL OAuth
cookie snapshots. Now interpolates the matched prefix only.
- Docker port-prefix mismatch: entrypoint.sh / run-emulator.sh / cloud-init
user-data still produced NEXT_PUBLIC_STACK_PORT_PREFIX while the dashboard
sentinel + consumers expected NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX — a silent
self-host regression. Producers updated (legacy name accepted as input).
- OAuth authorize route set only stack-oauth-inner-*; now dual-writes
hexclave-oauth-inner-* (the callback already reads either).
- mcp.test.ts: tool-list assertions updated for the added ask_hexclave tool.
- Dashboard internal-project-headers.ts / feedback-form.tsx now emit
x-hexclave-* request headers.
Verified: changed files typecheck-clean; lint green for backend, dashboard,
e2e-tests. (Backend full typecheck remains blocked only by the fresh-worktree
Prisma/codegen gap — unrelated to these changes.)
…ts.test snapshots Found while running e2e tests against PR 1 changes: - snapshot-serializer.ts already hid x-stack-request-id (non-deterministic); with the dual-emit, x-hexclave-request-id was leaking into snapshots. Added it to the hidden list — matches the existing x-stack-request-id treatment. - projects.test.ts: 2 inline snapshots updated to include the new x-hexclave-known-error header alongside x-stack-known-error (PR 1 dual-emit working correctly — both headers are deterministic and belong in snapshots). Verified: pnpm test run apps/e2e/.../mcp.test.ts → 6/6 pass; projects.test.ts → 11/11 pass against the running backend on cl/hexclave-pr1.
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
|
Important Review skippedToo many files! This PR contains 300 files, which is 150 over the limit of 150. To get a review, narrow the scope: ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (300)
You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
…ery param
Source-of-truth schema in apps/backend/.../oauth/authorize/[provider_id]/route.tsx changed: stack_response_mode lost its .default("redirect") (resolved manually now: hexclave_response_mode ?? stack_response_mode ?? "redirect"), and hexclave_response_mode was added. The OpenAPI JSON is generated from the schema; this brings the committed artifacts in sync. Fixes the 'Check for uncommitted changes' CI step.
![vercel[bot]](https://avatars.githubusercontent.com/in/8329?s=60&v=4){kind=small}
…rs in snapshots Two fixes for PR #1475 CI: 1. Snapshot serializer hides x-hexclave-known-error and x-hexclave-actual-status alongside the already-hidden x-hexclave-request-id. These carry identical values to their x-stack-* counterparts (dual-emit), so hiding the duplicates keeps existing snapshots stable instead of forcing a suite-wide regen. Resolves the bulk of E2E snapshot mismatches. 2. Vercel Agent review comment: response_mode fields (both stack_ and hexclave_ variants) carry .meta({ openapiField: { description } }) documenting the runtime default behavior ('redirect' if neither set), which the manual ?? resolution at the use site applies. OpenAPI docs regenerated to reflect the descriptions.
…-write Previous push (3f51ed5) cut e2e failures from 96 → 20. The remaining 20 came from three distinct shapes the first pass missed; all are test-only fixes for already-correct production behavior. 1. authorize.test.ts:39,48 — two duplicate copies of the same stack-oauth-inner-* set-cookie regex assertion that lived in the test file instead of backend-helpers. Switched to getSetCookie() with the prefix-tolerant regex (same fix shape as backend-helpers.ts:803). 2. snapshot-serializer.ts — extended the existing 'hide dual-emitted hexclave-* duplicates' strategy from headers to cookies. The hideHeaders list already filters x-hexclave-{request-id,known-error, actual-status} so dual-emit doesn't bloat every response snapshot in the suite; the cookie path missed the equivalent treatment, so every OAuth response snapshot was picking up an extra <deleting cookie 'hexclave-oauth-inner-*'> line. Added a hiddenSetCookieNamePrefixes list and pre-filter the Headers' Set-Cookies before nicify recurses. WeakSet guards against infinite recursion on the filtered copy. 3. internal/projects.test.ts — two inline snapshots were regenerated by commit 4b16cc5 with x-hexclave-known-error visible, before that header name was added to the serializer's hideHeaders list (lines 36-37). The serializer correctly hides it now, so the snapshot entries are over-inclusive. Removed the two x-hexclave-known-error lines so the snapshots match what the serializer emits.
N2D4
approved these changes
May 23, 2026
The Hexclave{Client,Server,Admin}App identifiers are declared in
interfaces/{client,server,admin}-app.ts as both a 'type' alias and a
'const' value (namespace merging). The plain value re-export in
apps/index.ts and stack-app/index.ts already carries the type half,
so listing the same name again under 'export type { ... }' a few lines
later redeclares it — TS2300 Duplicate identifier.
Local typecheck looked clean because packages/{js,react,stack,...} are
gitignored and locally stale; CI regenerates them in the pre-preinstall
hook (scripts/generate-sdks.ts), so it sees the freshly-generated
duplicates. Verified with 'pnpm --filter @stackframe/template
run typecheck' and 'pnpm --filter @stackframe/js run typecheck' after
re-running 'pnpm run generate-sdks' — both clean.
…s-domain, mcp)
Three e2e test files were asserting against the pre-rename stack-* /
ask_stack_auth identifiers, but the SDK and MCP server now emit only
the hexclave-* names. The read-side fallbacks (legacy refresh/access
cookie reads, cross-domain query param reads via the shared helper)
remain intact, so old clients still work end-to-end — these test
updates just track the *write/emit* side, which was straight-renamed.
apps/e2e/tests/js/cookies.test.ts (4 failing tests)
Refresh cookie writes use the hexclave-refresh-* prefix only
(client-app-impl.ts: _refreshTokenCookieName), so the test helpers
getDefaultRefreshCookieName / getCustomRefreshCookieName and the
literal startsWith("stack-refresh-") check in the trusted-parent-
domains test were updated to match. The two remaining stack-*
references (the _getDomainFromCustomRefreshCookieName negative-case
test at line 332 and the stack-access fallback read at line 353)
are intentional — they exercise the legacy-fallback paths in
_getDomainFromCustomRefreshCookieName and _getTokensFromCookies,
which still iterate both prefixes.
apps/e2e/tests/js/cross-domain-auth.test.ts (3 failing tests)
redirect-page-urls.ts: crossDomainAuthQueryParams emits and reads
only the hexclave_cross_domain_* names. All 12 stack_cross_domain_*
references in the test (both URL-set helpers that simulate inbound
redirect-back URLs and the searchParams.get assertions) renamed
wholesale.
apps/e2e/tests/backend/endpoints/api/v1/internal/mcp.test.ts (3 failing tests)
apps/mcp/src/mcp-handler.ts only registers ask_hexclave (the PR
description's "registered alongside ask_stack_auth" claim doesn't
match the actual handler — there is no server.tool('ask_stack_auth')
call). The inline snapshot had been hand-written expecting both
tools; replaced with the single-tool snapshot. Same for the public
endpoint matchObject and the validation-error test (which called
ask_stack_auth and got tool-not-found instead of the expected
invalid-arguments error — switched to ask_hexclave).
Verified: pnpm --filter @stackframe/e2e-tests run typecheck is clean.
The actual e2e assertions need a running backend to fully verify, so
final confirmation is via CI.
5 tasks
# Conflicts: # apps/backend/src/lib/emails-low-level.tsx # apps/backend/src/lib/external-db-sync.ts # apps/backend/src/lib/redirect-urls.tsx # apps/e2e/tests/backend/endpoints/api/v1/auth/sessions/index.test.ts # apps/e2e/tests/js/cross-domain-auth.test.ts # packages/template/src/lib/stack-app/apps/implementations/client-app-impl.ts # packages/template/src/lib/stack-app/url-targets.test.ts # packages/template/src/lib/stack-app/url-targets.ts
…_domain params Three test files held inline snapshots that captured the boilerplate HexclaveAssertionError disclaimer line. The class itself had been renamed StackAssertionError -> HexclaveAssertionError, and the snapshots already used the new class name -- but the disclaimer text in stack-shared/utils/errors.tsx was also updated to 'an error in Hexclave (formerly Stack Auth)', which the snapshots still had as 'an error in Stack'. Updated all three (the third generates into js/stack/react/ tanstack-start url-targets.test.ts via generate-sdks, fanning out to 15 of the 17 snapshot failures in CI): apps/backend/src/lib/redirect-urls.test.tsx:95 packages/stack-shared/src/utils/redirect-urls.tsx:246 packages/template/src/lib/stack-app/url-targets.test.ts:108,121,212 Separately, apps/e2e/tests/js/cross-domain-auth.test.ts lines 249-252 still set stack_cross_domain_auth/state/code_challenge/ after_callback_redirect_url on the simulated redirect-back URL. redirect-page-urls.ts now reads only hexclave_cross_domain_* (legacy fallback was dropped in 47e7c6e), so the SDK no longer recognised the URL as a cross-domain handoff, took a non-handoff path, and the backend rejected the fake project ID 12121212-... before the test's spy on _createCrossDomainAuthRedirectUrl could fire. The earlier fix commit renamed the other 12 occurrences in this file but missed these four. Renamed to hexclave_cross_domain_*. Verified locally: stack-shared/redirect-urls.tsx 6/6 template/url-targets.test.ts 20/20 backend/redirect-urls.test.tsx 33/33 js,stack,react,tanstack-start url-targets 80/80 (20x4) e2e/cross-domain-auth.test.ts 17/17
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
No issues found across 341 files
Partial review: This PR has more than 50 files, so cubic reviewed the highest-priority files first. During the trial, paid plans get a higher file limit.
You can try an ultrareview to bypass the file limit, comment @cubic-dev-ai ultrareview. Learn more.
Re-trigger cubic
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Stacked on #1468 (
docs/hexclave-rename-plan— the plan doc). Diff vs that base = the actual PR 1 code.This is PR 1 of the Hexclave rebrand: the invisible compatibility layer. Everything is additive. Old SDKs, old wire identifiers, and old env var names keep working unchanged. The backend dual-accepts and dual-emits; new SDK code emits
x-hexclave-*headers and thehexclave_Bearer prefix; cookies dual-write; env vars dual-read across every category. No user-visible rebranding lands here — that's PR 2.See
RENAME-TO-HEXCLAVE.md→ "PR 1 implementation guide" for the full per-work-area spec, file pointers, and chosen approach.What's implemented (all 14 PR-1 work-areas)
Hexclave*aliases for the user-facingStack*exports added inpackages/template; codegen propagates them to@stackframe/{js,stack,react,tanstack-start}. React-only aliases correctly excluded from@stackframe/js. (e60550a2)decodeAccessTokenaccepts bothapi.stack-auth.comandapi.hexclave.comissuers. Signing unchanged. (fc781def)x-hexclave-*→x-stack-*at the existing empty proxy hook (sosmart-request.tsxand every route schema keep working unchanged); CORS allowlists extended via a derive-once helper. (2a056eac)ask_hexclave— registered alongsideask_stack_authvia a shared helper;ask_stack_authbehavior byte-identical. (30ffd604)window.HexclaveDevToolexposed alongsidewindow.StackDevTool. (32131ea7)7fed864a):getEnvVariableprefix-transform (HEXCLAVE first, STACK fallback); dashboard + template client env files dual-read;turbo.jsonglobalEnv;NEXT_PUBLIC_STACK_PORT_PREFIXrenamed outright across ~82 files including docker.stack-access/-refresh-*and custom-domain variants), OAuth-state (stack-oauth-{inner,outer}-*), and low-risk cookies (stack-is-https,stack-last-seen-changelog-version). Bypass sites patched (backend OAuth callback, dashboard remote-dev auth route, impersonation snippets, snapshot serializer).stackauth_andhexclave_; emitshexclave_. Discovery correction: this is purely SDK-internal — the backend never parses it.x-hexclave-{request-id,actual-status,known-error}; SDKs dual-read (new first, stack fallback).client/server/admin-interface.ts+ dashboardapi-headers.ts+internal-project-headers.ts+feedback-form.tsxswitched tox-hexclave-*. Plusstack_response_modequery param.stack:session-replay:v1dual-read so in-progress recordings survive SDK upgrades;stack_mfa_attempt_codedual-read.oauth/authorizeacceptshexclave_response_modeandstack_response_mode;stack-init-idrenamed.Symbol.for— app-internals symbol gets a parallelSymbol.for("Hexclave--app-internals")getter on each attach site (no read-site churn — old symbol still attached). 3 file-private symbols renamed outright.hexclave.config.ts, fall back tostack.config.tsat every discovery site (CLI / dashboard / backend / local-emulator);initwrites the new filename; CLI credentials path migrates.StackAssertionError,StackClient/Server/AdminInterfacerenamed outright (no alias, per the "internal-only → rename" rule). ~264 files touched.21217fbe) — three real bugs found by parallel review agents and fixed:snapshot-serializer.tswas interpolating the wholekeyedCookieNamePrefixesarray (${arr}) — adding a second prefix would have corrupted every OAuth-cookie snapshot, not just new ones.entrypoint.sh/run-emulator.sh/cloud-inituser-datawere still producingNEXT_PUBLIC_STACK_PORT_PREFIXwhile the dashboard sentinel + consumers had been renamed; silent self-host regression (custom port prefix would be ignored).hexclave-oauth-inner-*dual-write in the OAuth authorize route — callback's fallback masked it but the dual-write was specified by the plan.mcp.test.tstool-list assertions updated to includeask_hexclave; two dashboard header-emit sites switched tox-hexclave-*for consistency.4b16cc5d) —x-hexclave-request-idadded to the hidden-headers list (mirroringx-stack-request-idtreatment), and 2 sample inline snapshots regenerated inprojects.test.tsto include the new dual-emitted headers.Verification
pnpm typecheck— clean (the fresh-worktree@/.source/ Prisma codegen gap instack-docsis pre-existing and unrelated).pnpm lint— 29/29 packages green.pnpm exec turbo run build --filter=./packages/*— 13/13 packages build (including@stackframe/stack-clionce the dashboard standalone is present).cl/hexclave-pr1:pnpm test run apps/e2e/tests/backend/endpoints/api/v1/internal/mcp.test.ts— 6/6 pass (verifies the newask_hexclavetool — the hand-written inline snapshot matched actual MCP server output).pnpm test run apps/e2e/tests/backend/endpoints/api/v1/internal/projects.test.ts— 11/11 pass (verifies wire dual-accept + dual-emit end-to-end; the snapshot serializer fix was found and applied during this check).A four-agent parallel review pass also audited the full diff for logic/runtime bugs across the work-areas (wire headers + JWT, cookies + bearer + symbols, env vars, query params + config + MCP + aliases). All in-slice review verdicts were ✓ except the three bugs listed above, which are now fixed.
Known follow-ups (out of scope for this PR)
x-hexclave-{known-error,actual-status}alongsidex-stack-*, which legitimately appears in inline snapshots throughoutapps/e2e. Two were regenerated here as a sample; the rest should regen withvitest -uin CI.PORT_PREFIX—entrypoint.shstill readsSTACK_*env vars directly (the JS-sidegetEnvVariabletransform doesn't help the shell). JS consumers dual-read so it works in practice; full shell-level dual-read is a deeper self-host follow-up.@stackframe/stack-clibuild ordering — pre-existing; needsbuild:rde-standalonefirst. Not affected by this PR.Test plan
vitest -uto absorb dual-emit snapshot deltas, then committed back)x-stack-*) still authenticates against the new backendx-hexclave-*/Bearer hexclave_*) still authenticates against an old backend during deploy orderingnpx @stackframe/stack-cli@latest init(new onboarding entrypoint) generateshexclave.config.tsstack.config.ts-only project still resolves (no migration required)