Thanks to visit codestin.com
Credit goes to github.com

Skip to content

docs: Stack Auth → Hexclave rebrand plan#1468

Draft
BilalG1 wants to merge 5 commits into
devfrom
docs/hexclave-rename-plan
Draft

docs: Stack Auth → Hexclave rebrand plan#1468
BilalG1 wants to merge 5 commits into
devfrom
docs/hexclave-rename-plan

Conversation

@BilalG1
Copy link
Copy Markdown
Collaborator

@BilalG1 BilalG1 commented May 21, 2026

Summary

Adds the v6 rebrand plan (RENAME-TO-HEXCLAVE.md) covering every renameable identifier across the codebase and how each one is handled.

Highlights:

  • Tier 0 — wire identifiers (dual-accept / dual-emit / dual-write): 21 request headers, 3 response headers, Bearer stackauth_* prefix, all stack-* cookies (auth + OAuth state + low-risk UI), 3 JWT issuer variants, mobile OAuth URL scheme, MCP tool name, config filename. Each old form stays readable indefinitely; new form is preferred and emitted by new code.
  • Tier 1 — SDK aliases: every public Stack* class/component/hook/type gets a Hexclave* alias via re-exports in packages/template; codegen propagates to react/stack/js. Swift SDK split into two separate SPM packages (frozen StackAuth + new Hexclave).
  • Tier 2 — NPM packages: 10 @stackframe/* packages dual-published as @hexclave/* via a rewrite-then-republish step appended to .github/workflows/npm-publish.yaml.
  • Env var taxonomy with 5 categories — customer-facing dual-read, framework-internal dual-read, self-host operator vars out of scope, GitHub onboarding split into secret names vs process env vars, build/dev/test stays as-is.
  • Customer-facing surfaces the plan covers: @stackframe/emails virtual module, dashboard sandbox window.Stack* globals + iframe message types, KnownErrors message templates, init wizard, dashboard setup snippets.
  • Implementation realities section documents architectural mismatches discovered during pre-PR-1 review (route-level header schemas, JWT validator URL-builder pattern, npm publish workspace lockfile issue, etc.).
  • PR 1 verification matrix covers auth wire, cookies, env vars, JWT, MCP, CLI/config, packages, Swift, docs, migrations, tests + CI.
  • 2-PR rollout: PR 1 ships every dual-support shim additively; PR 2 (12+ months later) removes only the safely-removable fallbacks. Wire identifiers stay indefinitely; PR 3+ could remove specific shims once telemetry shows usage drops to zero.

Review focus

  • Anything in the codebase that touches stack/Stack/stackframe and isn't covered.
  • Any implementation pattern proposed in the plan that won't drop in cleanly against the current code.
  • Disagreements on classification (which identifiers should stay vs. dual-support vs. rebrand cosmetically).

Test plan

  • No code changes; review the document for completeness and correctness against the actual codebase.

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.
@vercel
Copy link
Copy Markdown

vercel Bot commented May 21, 2026

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated (UTC)
stack-auth-hosted-components Ready Ready Preview, Comment May 22, 2026 7:12pm
stack-auth-mcp Ready Ready Preview, Comment May 22, 2026 7:12pm
stack-auth-skills Ready Ready Preview, Comment May 22, 2026 7:12pm
stack-backend Ready Ready Preview, Comment May 22, 2026 7:12pm
stack-dashboard Ready Ready Preview, Comment May 22, 2026 7:12pm
stack-demo Ready Ready Preview, Comment May 22, 2026 7:12pm
stack-docs Ready Ready Preview, Comment May 22, 2026 7:12pm
stack-preview-backend Ready Ready Preview, Comment May 22, 2026 7:12pm
stack-preview-dashboard Ready Ready Preview, Comment May 22, 2026 7:12pm

@coderabbitai
Copy link
Copy Markdown
Contributor

coderabbitai Bot commented May 21, 2026

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2519a3a6-c4e2-4953-a9d4-3571ad3ce985

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/hexclave-rename-plan

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

…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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant