stack/apps/dev-launchpad/public/index.html
BilalG1 f7e389809e
Some checks failed
all-good: Did all the other checks pass? / all-good (push) Has been cancelled
Ensure Prisma migrations are in sync with the schema / check_prisma_migrations (22.x) (push) Has been cancelled
DB migration compat / Check if migrations changed (push) Has been cancelled
Docker Server Build and Push / Docker Build and Push Server (push) Has been cancelled
Docker Server Build and Run / docker (push) Has been cancelled
Runs E2E API Tests (Local Emulator) / E2E Tests (Local Emulator, Node ${{ matrix.node-version }}) (22.x) (push) Has been cancelled
Runs E2E API Tests / E2E Tests (Node ${{ matrix.node-version }}, Freestyle ${{ matrix.freestyle-mode }}) (mock, 22.x) (push) Has been cancelled
Runs E2E API Tests / E2E Tests (Node ${{ matrix.node-version }}, Freestyle ${{ matrix.freestyle-mode }}) (prod, 22.x) (push) Has been cancelled
Runs E2E API Tests with custom port prefix / build (22.x) (push) Has been cancelled
Runs E2E Fallback Tests / E2E Fallback Tests (Node ${{ matrix.node-version }}) (22.x) (push) Has been cancelled
Lint & build / lint_and_build (24) (push) Has been cancelled
TOC Generator / TOC Generator (push) Has been cancelled
DB migration compat / Back-compat — Current branch migrations with ${{ needs.check-migrations-changed.outputs.base_branch }} branch code (push) Has been cancelled
DB migration compat / Forward-compat — Current branch code with ${{ needs.check-migrations-changed.outputs.base_branch }} branch migrations (push) Has been cancelled
DB migration compat / No migration changes (skipped) (push) Has been cancelled
feat(hexclave): PR 1 — wire compatibility layer (invisible) (#1475)
## 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 the
`hexclave_` 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`](./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)

- **SDK export aliases** — `Hexclave*` aliases for the user-facing
`Stack*` exports added in `packages/template`; codegen propagates them
to `@stackframe/{js,stack,react,tanstack-start}`. React-only aliases
correctly excluded from `@stackframe/js`. (`e60550a2`)
- **JWT issuer dual-accept** — `decodeAccessToken` accepts both
`api.stack-auth.com` and `api.hexclave.com` issuers. Signing unchanged.
(`fc781def`)
- **Request-header dual-accept** — backend + dashboard proxies normalize
`x-hexclave-*` → `x-stack-*` at the existing empty proxy hook (so
`smart-request.tsx` and every route schema keep working unchanged); CORS
allowlists extended via a derive-once helper. (`2a056eac`)
- **MCP `ask_hexclave`** — registered alongside `ask_stack_auth` via a
shared helper; `ask_stack_auth` behavior byte-identical. (`30ffd604`)
- **Dev-tool** — DOM ids + header emit switched.
`window.HexclaveDevTool` exposed alongside `window.StackDevTool`.
(`32131ea7`)
- **The big consolidated commit** (`7fed864a`):
- **Env vars** — central `getEnvVariable` prefix-transform (HEXCLAVE
first, STACK fallback); dashboard + template client env files dual-read;
`turbo.json` globalEnv; `NEXT_PUBLIC_STACK_PORT_PREFIX` renamed outright
across ~82 files including docker.
- **Cookies** — dual-write/dual-read auth (`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).
- **Bearer prefix** — SDK token parser accepts both `stackauth_` and
`hexclave_`; emits `hexclave_`. Discovery correction: this is purely
SDK-internal — the backend never parses it.
- **Response headers** — backend dual-emits
`x-hexclave-{request-id,actual-status,known-error}`; SDKs dual-read (new
first, stack fallback).
- **SDK request-header emit switch** —
`client/server/admin-interface.ts` + dashboard `api-headers.ts` +
`internal-project-headers.ts` + `feedback-form.tsx` switched to
`x-hexclave-*`. Plus `stack_response_mode` query param.
- **Storage keys** — dev-tool / cli-auth / oauth-button / docs keys
renamed (straight); `stack:session-replay:v1` dual-read so in-progress
recordings survive SDK upgrades; `stack_mfa_attempt_code` dual-read.
- **Query params** — cross-domain params dual-emit/dual-accept via
shared helpers; backend `oauth/authorize` accepts
`hexclave_response_mode` and `stack_response_mode`; `stack-init-id`
renamed.
- **`Symbol.for`** — app-internals symbol gets a parallel
`Symbol.for("Hexclave--app-internals")` getter on each attach site (no
read-site churn — old symbol still attached). 3 file-private symbols
renamed outright.
- **Config discovery** — prefer `hexclave.config.ts`, fall back to
`stack.config.ts` at every discovery site (CLI / dashboard / backend /
local-emulator); `init` writes the new filename; CLI credentials path
migrates.
- **Internal renames** — `StackAssertionError`,
`StackClient/Server/AdminInterface` renamed outright (no alias, per the
"internal-only → rename" rule). ~264 files touched.
- **Review-pass fixes** (`21217fbe`) — three real bugs found by parallel
review agents and fixed:
- `snapshot-serializer.ts` was interpolating the whole
`keyedCookieNamePrefixes` array (`${arr}`) — adding a second prefix
would have corrupted **every** OAuth-cookie snapshot, not just new ones.
- **Docker port-prefix producer/consumer mismatch** —
`entrypoint.sh`/`run-emulator.sh`/cloud-init `user-data` were still
producing `NEXT_PUBLIC_STACK_PORT_PREFIX` while the dashboard sentinel +
consumers had been renamed; silent self-host regression (custom port
prefix would be ignored).
- **Missing `hexclave-oauth-inner-*` dual-write** in the OAuth authorize
route — callback's fallback masked it but the dual-write was specified
by the plan.
- Plus: `mcp.test.ts` tool-list assertions updated to include
`ask_hexclave`; two dashboard header-emit sites switched to
`x-hexclave-*` for consistency.
- **E2E snapshot serializer follow-up** (`4b16cc5d`) —
`x-hexclave-request-id` added to the hidden-headers list (mirroring
`x-stack-request-id` treatment), and 2 sample inline snapshots
regenerated in `projects.test.ts` to include the new dual-emitted
headers.

## Verification

- **`pnpm typecheck`** — clean (the fresh-worktree `@/.source` / Prisma
codegen gap in `stack-docs` is pre-existing and unrelated).
- **`pnpm lint`** — 29/29 packages green.
- **`pnpm exec turbo run build --filter=./packages/*`** — 13/13 packages
build (including `@stackframe/stack-cli` once the dashboard standalone
is present).
- **Live E2E** against a running backend on `cl/hexclave-pr1`:
- `pnpm test run
apps/e2e/tests/backend/endpoints/api/v1/internal/mcp.test.ts` — **6/6
pass** (verifies the new `ask_hexclave` tool — 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)

- **E2E snapshots across the rest of the suite** — backend now
dual-emits `x-hexclave-{known-error,actual-status}` alongside
`x-stack-*`, which legitimately appears in inline snapshots throughout
`apps/e2e`. Two were regenerated here as a sample; the rest should regen
with `vitest -u` in CI.
- **Docker shell env vars beyond `PORT_PREFIX`** — `entrypoint.sh` still
reads `STACK_*` env vars directly (the JS-side `getEnvVariable`
transform 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-cli` build ordering** — pre-existing; needs
`build:rde-standalone` first. Not affected by this PR.

## Test plan

- [ ] CI runs full e2e suite (with `vitest -u` to absorb dual-emit
snapshot deltas, then committed back)
- [ ] Spot-check: an old SDK build (emitting only `x-stack-*`) still
authenticates against the new backend
- [ ] Spot-check: a new SDK (emitting `x-hexclave-*` / `Bearer
hexclave_*`) still authenticates against an old backend during deploy
ordering
- [ ] Manual: `npx @stackframe/stack-cli@latest init` (new onboarding
entrypoint) generates `hexclave.config.ts`
- [ ] Manual: existing `stack.config.ts`-only project still resolves (no
migration required)

---------

Co-authored-by: bilal <bilal@stack-auth.com>
2026-05-23 17:24:55 -07:00

439 lines
14 KiB
HTML

<!DOCTYPE html>
<html>
<head>
<title>Stack Auth Dev Launchpad</title>
<script src="./env-config.js"></script>
<style>
body {
font-family: Arial, sans-serif;
background-color: #e0f0e0;
padding-left: 16px;
padding-right: 16px;
}
.apps-container {
display: flex;
flex-direction: row;
flex-wrap: wrap;
gap: 16px;
}
.apps-container > a {
border: 1px solid #8888;
background-color: #fff;
padding: 0px 4px 8px 4px;
width: 120px;
text-decoration: none;
display: flex;
flex-direction: column;
align-items: center;
gap: 12px;
position: relative;
}
.apps-container > a.important {
background-color: #fee;
}
.apps-container > a.unimportant {
opacity: 0.2;
}
.apps-container > a.unimportant:hover {
opacity: 0.5;
}
.apps-container > a:hover {
border-color: #888;
transition: opacity 0.1s ease-in-out;
}
.apps-container > a > div > img {
height: 68px;
}
.apps-container > a > .description {
text-align: center;
font-size: 12px;
color: #888;
}
.apps-container > a > .port {
padding-right: 0.5px;
padding-top: 1px;
align-self: flex-end;
font-size: 12px;
color: #888;
}
.apps-container > a > .hover-description {
display: none;
position: absolute;
top: 100%;
left: -1px;
pointer-events: none;
z-index: 1000;
white-space: pre;
background-color: #ffc;
border: 1px solid #888;
padding: 2px;
color: #0008;
font-size: 12px;
}
.apps-container > a:hover > .hover-description {
display: block;
}
</style>
</head>
<body>
<h1>Stack Auth Dev Launchpad</h1>
<div class="apps-container"></div>
<hr />
<div class="apps-container"></div>
<hr />
<div class="apps-container"></div>
<h2 style="margin-top: 64px;">Background services</h2>
<ul class="background-services"></ul>
<noscript>
This page requires JavaScript.
</noscript>
<script>
const derivePrefixFromLocation = () => {
const port = window.location.port;
if (!port || port.length < 2) return "81";
return port.slice(0, -2);
};
const stackPortPrefix = window.NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX || derivePrefixFromLocation();
window.NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX = stackPortPrefix;
const withPrefix = (suffix) => `${stackPortPrefix}${suffix}`;
// Depending on the port prefix, set the color to light grey (port 91), light purple (port 92), papyrus yellow (port 93), or default otherwise
const color = {
"91": "#f8f8f8",
"92": "#fff8e0",
"93": "#e0e0ff",
}[stackPortPrefix] || undefined;
document.body.style.backgroundColor = color;
const backgroundServices = [
{ suffix: "28", label: "PostgreSQL" },
{ suffix: "34", label: "PostgreSQL Replica (with replication lag)" },
{ suffix: "29", label: "Inbucket SMTP" },
{ suffix: "30", label: "Inbucket POP3" },
{ suffix: "31", label: "OTel collector" },
{ suffix: "21", label: "S3 mock" },
{ suffix: "22", label: "Freestyle mock" },
{ suffix: "24", label: "LocalStack Gateway (AWS mock)" },
{ suffix: "25", label: "QStash mock" },
{ suffix: "33", label: "ClickHouse native interface" },
{ suffix: "39", label: "SpacetimeDB (MCP call log)" },
{ range: ["50", "99"], label: "Reserved for LocalStack (external services)" },
];
const backgroundList = document.querySelector(".background-services");
backgroundList.innerHTML = backgroundServices.map((service) => {
const portText = service.range
? `${withPrefix(service.range[0])}-${withPrefix(service.range[1])}`
: withPrefix(service.suffix);
return `<li>${portText}: ${service.label}</li>`;
}).join("");
const apps = [
{
name: "Dashboard",
portSuffix: "01",
description: [
"Src: ./apps/dashboard",
"Prod: https://app.stack-auth.com",
],
img: "https://www.svgrepo.com/show/507260/dashboard.svg",
importance: 2,
},
{
name: "Backend",
portSuffix: "02",
description: [
"Src: ./apps/backend",
"Prod: https://api.stack-auth.com",
],
img: "https://www.svgrepo.com/show/340122/datastore.svg",
importance: 2,
},
{
name: "MCP",
portSuffix: "42",
description: [
"Src: ./apps/mcp",
"Prod: https://mcp.stack-auth.com/mcp",
],
importance: 2,
},
{
name: "Demo app",
portSuffix: "03",
description: [
"Src: ./examples/demo",
"Prod: https://demo.stack-auth.com",
],
importance: 2,
},
{
name: "TanStack Start demo",
portSuffix: "43",
description: [
"Src: ./examples/tanstack-start-demo",
"Alpha SDK integration demo",
],
img: "https://tanstack.com/favicon.ico",
importance: 2,
},
{
name: "Docs",
portSuffix: "26",
description: [
"Src: ./docs",
"Prod: https://docs.stack-auth.com",
],
img: "https://www.svgrepo.com/show/448400/docs.svg",
importance: 2,
},
{
name: "Mintlify docs",
portSuffix: "04",
description: [
"Src: ./docs-mintlify",
],
img: "https://www.svgrepo.com/show/448400/docs.svg",
importance: 2,
},
{
name: "Hosted Components",
portSuffix: "09",
description: [
"Src: ./apps/hosted-components",
],
importance: 2,
},
{
name: "Inbucket",
portSuffix: "05",
img: "https://www.svgrepo.com/show/533176/at-sign.svg",
importance: 1,
description: [
"Email mock",
],
},
{
name: "Prisma Studio",
portSuffix: "06",
importance: 1,
img: "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcS95TdAw63YPAPcUpvRl4imIf-VJ1sGHnEvbw&s",
description: [
"Database interface",
],
},
{
name: "Jaeger UI (OTel)",
portSuffix: "07",
description: [
"Performance & tracing",
],
importance: 1,
img: "https://www.jaegertracing.io/img/jaeger-icon-reverse-color.svg",
},
{
name: "examples/docs-examples",
portSuffix: "08",
description: [
"Src: ./examples/docs-examples",
],
},
{
name: "examples/cjs-test",
portSuffix: "10",
description: [
"Src: ./examples/cjs-test",
],
},
{
name: "examples/e-commerce",
portSuffix: "11",
description: [
"Src: ./examples/e-commerce",
],
},
{
name: "examples/middleware",
portSuffix: "12",
description: [
"Src: ./examples/middleware",
],
},
{
name: "Svix server",
portSuffix: "13",
importance: 1,
img: "data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyBpZD0iTGF5ZXJfMiIgZGF0YS1uYW1lPSJMYXllciAyIiB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZlcnNpb249IjEuMSIgdmlld0JveD0iODQuOSA4NC45IDM0NyAzNDciPgogIDxkZWZzPgogICAgPHN0eWxlPgogICAgICAuY2xzLTEgewogICAgICAgIGZpbGw6ICNmZmY7CiAgICAgIH0KCiAgICAgIC5jbHMtMSwgLmNscy0yIHsKICAgICAgICBzdHJva2Utd2lkdGg6IDBweDsKICAgICAgfQoKICAgICAgLmNscy0yIHsKICAgICAgICBmaWxsOiAjMmM3MGZmOwogICAgICB9CiAgICA8L3N0eWxlPgogIDwvZGVmcz4KICA8ZyBpZD0iTGF5ZXJfMS0yIiBkYXRhLW5hbWU9IkxheWVyIDEtMiI+CiAgICA8Y2lyY2xlIGNsYXNzPSJjbHMtMSIgY3g9IjI1OC40IiBjeT0iMjU4LjQiIHI9IjE3My41Ii8+CiAgICA8Zz4KICAgICAgPHBhdGggY2xhc3M9ImNscy0yIiBkPSJNMzYwLjgsMjMyLjljLTI4LjgtMS40LTU1LjctMTcuMi02OC4yLTQ1LTUuNS0xMi4zLTE3LjgtMjAuNC0zMS4zLTIwLjgtMjguNi0uOC00Ni43LDM1LjEtMjguNyw1Ny42LDYuMiw3LjgsMTUuNCwxMi4xLDI3LjUsMTIuOWgwYzIzLjQsMS43LDQzLjUsMTEuOCw1Ni44LDI4LjUsMjQuNCwzMC43LDIwLjksNzcuMS03LjQsMTA0LTM0LjEsMzIuNS05MS4xLDI1LjgtMTE3LjEtMTMuMi0yLjMtMy41LTQuMy03LjEtNi4xLTEwLjktNS41LTEyLjMtMTcuOC0yMC40LTMxLjMtMjAuOC0xMy45LS40LTI3LDQuOS0zNS4zLDEzLjgsMjcuMyw0Ni45LDc3LjcsNzguNywxMzUuOSw3OS43LDg4LjYsMS41LDE2MS43LTY5LDE2My4yLTE1Ny42LjMtMTQuOS0xLjYtMjkuNC01LjEtNDMuMi43LDIuOS0yMi4zLDEwLjktMjQuOCwxMS42LTkuMiwyLjctMTguNywzLjctMjgsMy4zaDBaIi8+CiAgICAgIDxwYXRoIGNsYXNzPSJjbHMtMiIgZD0iTTE1NiwyODMuNmMyOS40LjcsNTYuMSwxOC41LDY4LjIsNDUuMyw1LjUsMTIuMywxNy44LDIwLjQsMzEuMywyMC44LDkuNC4zLDE4LjMtMy4yLDI1LjItOS43LDEyLjgtMTIuMSwxNC41LTM0LjEsMy41LTQ4LTYuMi03LjgtMTUuNC0xMi4xLTI3LjUtMTIuOWgwYy0yMy40LTEuNy00My41LTExLjgtNTYuOC0yOC41LTI5LjYtMzcuMi0xNy05Mi41LDIzLjctMTE1LjQsMTEuOC02LjYsMjUuMi0xMC4yLDM4LjctOS44LDI5LjQuNyw1Ni4xLDE4LjUsNjguMiw0NS4zLDUuNSwxMi4zLDE3LjgsMjAuNCwzMS4zLDIwLjgsMTQsLjQsMjctNC45LDM1LjMtMTMuOC0yNy4zLTQ2LjktNzcuNy03OC43LTEzNS45LTc5LjgtODguNi0xLjUtMTYxLjYsNjkuMS0xNjMuMiwxNTcuNi0uMywxNC45LDEuNiwyOS40LDUuMiw0My4yLDE0LjktMTAuMSwzMy4zLTE1LjYsNTIuOS0xNS4yaDBaIi8+CiAgICA8L2c+CiAgPC9nPgo8L3N2Zz4=",
description: [
"Webhooks",
],
},
{
name: "OAuth mock server",
portSuffix: "14",
description: [
"Src: ./apps/mock-oauth-server",
],
},
{
name: "examples/supabase",
portSuffix: "15",
description: [
"Src: ./examples/supabase",
],
},
{
name: "PgHero",
portSuffix: "16",
description: [
"For database performance analysis",
],
importance: 1,
img: "https://pghero.dokkuapp.com/assets/pghero-88a0d052.png",
},
{
name: "PgHero (Replica)",
portSuffix: "35",
description: [
"For replica database performance analysis",
],
importance: 1,
img: "https://pghero.dokkuapp.com/assets/pghero-88a0d052.png",
},
{
name: "PgAdmin",
portSuffix: "17",
description: [
"For database administration",
],
importance: 1,
img: "https://www.w3schools.com/postgresql/screenshot_postgresql_pgadmin4_6.png",
},
{
name: "Supabase Studio",
portSuffix: "18",
path: "/project/default/editor",
description: [
"For database administration",
],
importance: 1,
img: "https://cdn.prod.website-files.com/655b60964be1a1b36c746790/655b60964be1a1b36c746d41_646dfce3b9c4849f6e401bff_supabase-logo-icon_1.png",
},
{
name: "Drizzle Gateway",
portSuffix: "33",
description: [
"Manage Drizzle configs",
],
importance: 1,
},
{
name: "WAL Info",
portSuffix: "38",
description: [
"Replication & WAL monitoring",
"Tracks primary/replica LSN positions",
"Decodes WAL to SQL statements",
],
importance: 1,
img: "https://www.svgrepo.com/show/374002/replication.svg",
},
{
name: "Internal Tool",
portSuffix: "41",
description: [
"Src: ./apps/internal-tool",
"MCP call review tool",
],
importance: 1,
},
{
name: "Bulldozer Studio",
portSuffix: "40",
description: [
"Bulldozer table graph and editor",
"Includes raw storage debug browser",
],
importance: 1,
img: "https://www.svgrepo.com/show/349299/database.svg",
},
{
name: "JS example",
portSuffix: "19",
description: [
"JavaScript example",
],
},
{
name: "React example",
portSuffix: "20",
description: [
"React example",
],
},
{
name: "ClickHouse HTTP",
portSuffix: "36",
description: [
"ClickHouse",
],
importance: 1,
img: "https://thumbs.bfldr.com/at/qkjfv3nvsv4rbwn94zmtb4t/v/1197417003?expiry=1764357242&fit=bounds&height=800&sig=NjEwNzA0OThjZmJiZDQzZmUwNjIyY2UxYzZiNGYxNmQ3NjJiYjc0OA%3D%3D&width=1100",
},
{
name: "Convex example",
portSuffix: "27",
importance: 0,
description: [
"Convex example",
],
},
{
name: "Lovable React 18 example",
portSuffix: "32",
importance: 0,
description: [
"Lovable React 18 example",
],
},
];
const appsContainers = document.querySelectorAll(".apps-container");
for (let i = 0; i < appsContainers.length; i++) {
const appContainer = appsContainers[i];
const importance = appsContainers.length - i - 1;
for (const app of apps) {
if ((app.importance ?? 0) === importance) {
// TODO escape HTML
appContainer.innerHTML += `
<a href="http://${`${stackPortPrefix}` === "81" ? "" : `p${stackPortPrefix}.`}localhost:${withPrefix(app.portSuffix)}${app.path ?? ""}" target="_blank" rel="noopener noreferrer" class="${app.importance === 2 ? "important" : app.importance === 1 ? "" : "unimportant"}">
<div class="port">:${withPrefix(app.portSuffix)}</div>
<div>
<img src=${app.img || `//localhost:${withPrefix(app.portSuffix)}/favicon.ico`} />
</div>
<span class="description">${app.name}</span>
${app.description ? `<div class="hover-description">${app.description.join("\n")}</div>` : ""}
</a>
`;
}
}
}
</script>
</body>
</html>