13 Commits

Author	SHA1	Message	Date
BilalG1	38ae913fc9	Rename STACK_* env vars to HEXCLAVE_* in env templates, with legacy dual-read (#1588) ... ## Summary Completes the env-var side of the Hexclave rebrand: every `STACK_*`-prefixed variable (including `NEXT_PUBLIC_STACK_*` and `VITE_STACK_*`) is renamed to `HEXCLAVE_*` across all checked-in `.env`, `.env.development`, and `.env.example` files (30 files, ~135 keys). Legacy `STACK_*` names keep working everywhere via dual-read, so **existing deployments, `.env.local` files, and self-hosted setups need no immediate migration**. ## How legacy names keep working - **Server code** already resolves `HEXCLAVE_*` first with `STACK_*` fallback via `getEnvVariable`. Direct `process.env.STACK_X` readers fed by the renamed files (prisma seed, e2e tests/helpers, internal-tool scripts, examples, `prisma.config.ts`) now read `HEXCLAVE_X || STACK_X`. - **Client code** (Next.js build-time inlining) uses literal dual-read expressions; the dashboard's `_inlineEnvVars` already had them. - **Docker/self-hosting**: `docker/server/entrypoint.sh` (shared by the server and local-emulator images) gets a generic two-way `HEXCLAVE_`↔`STACK_` env mirror — runs at startup and again before sentinel replacement — replacing the previous URL-trio-only mirror. Operators can use either prefix. ## The empty-placeholder trap (`||` vs `??`) The checked-in templates define empty placeholders (`HEXCLAVE_X=# comment` parses to `""` via dotenv). With `?? `-based fallbacks, that empty string would silently shadow a real value under the legacy name — including legacy vars set in Vercel/CI env at build time, since the tracked `.env` is present during builds. All fallback chains therefore treat empty-as-unset (`||`): - `getEnvVariable` and `getProcessEnv` in `packages/shared` - the dashboard/docs/example literal dual-reads - the generated SDK env getters (via `packages/template/scripts/generate-env.ts`; the generated `src/generated/env.ts` files are gitignored and regenerate at build) ## Other notable changes - Tests that override env now set the canonical `HEXCLAVE_*` name (it wins over `STACK_*`): e2e `cross-domain-auth`, backend `internal-feedback-emails` in-source test. - e2e `helpers.ts` port-prefix expansion loop also matches the `HEXCLAVE_` prefixes. - `docker/local-emulator/generate-env-development.mjs` reads source keys canonically (legacy fallback) and emits canonical keys; regenerated output matches. - `rotate-secrets.sh` falls back to `HEXCLAVE_DATABASE_CONNECTION_STRING`. - Docs code snippets (`docs/code-examples`) renamed outright to canonical names, consistent with #1571. - OAuth callback `console.warn` in `packages/template/src/lib/auth.ts` now says Hexclave. ## Migration note for the team Local `.env.local` files with legacy `STACK_*` overrides keep working **unless** the override targets a var that `.env.development` now sets to a real (non-empty) `HEXCLAVE_*` value — the canonical name wins over file precedence. Rename those keys in your `.env.local` once. ## Verification - `typecheck` + `lint` pass on every touched package (shared, backend, dashboard, e2e, internal-tool, cli, docs, template). Pre-existing failures on dev (`admin-app-impl.ts` typecheck, dashboard metrics-page errors) are unchanged (identical error counts with/without this change). - `getEnvVariable`/`getProcessEnv` fallback semantics smoke-tested directly (empty-HEXCLAVE → legacy fallback, HEXCLAVE wins when set, defaults intact). - `internal-feedback-emails` in-source vitest passes; emulator env generator `--check` passes; `bash -n` on touched shell scripts. - Two independent review agents audited the diff for correctness bugs and coverage gaps; all confirmed findings are fixed in the third commit. <!-- This is an auto-generated description by cubic. --> --- ## Summary by cubic Renamed all `STACK_*` env vars (including `NEXT_PUBLIC_STACK_*`/`VITE_STACK_*`) to `HEXCLAVE_*` across env templates and code, with dual‑read that treats empty as unset, detects conflicts, ignores post‑build sentinels, and falls back to legacy names. All GitHub Actions now use `HEXCLAVE_*`; local‑emulator e2e is fixed by setting `NEXT_PUBLIC_HEXCLAVE_IS_LOCAL_EMULATOR` in CI. - **Refactors** - Added conflict‑aware dual‑read helpers (prefer `HEXCLAVE_*`, empty‑as‑unset, ignore post‑build sentinels, preserve empty passthrough) and used them across `packages/shared` (resolver + tests), `apps/dashboard` inline/public envs (with tests), `apps/backend` Prisma config/seed and vitest (accept both prefixes), `packages/cli` (API/Dashboard URLs, project ID, `HEXCLAVE_EMULATOR_HOME`; tests), Docker (`entrypoint.sh` mirroring + `rotate-secrets.sh` DB URL), docs/components (`docs/src/lib/env.ts`), and examples; hosted/Vite apps now error if both spellings differ. - Port‑prefix expansion includes `HEXCLAVE_*`; backend tests use a new helper to resolve DB connection strings; Prisma prefers `HEXCLAVE_DATABASE_CONNECTION_STRING` with legacy fallback. - Generated SDK env getters use plain `HEXCLAVE_*` || `STACK_*` (no conflict throw); dashboard inline resolver preserves empty/sentinel passthrough to avoid build failures; docs/examples include dual‑read utilities. - Tests now stub canonical `HEXCLAVE_*` flags (e.g., plan limits, bot challenge, OAuth tokens, hosted handler) to avoid shadowing/conflict with committed defaults. - **Migration** - No immediate action; legacy `STACK_*` names still work. - If both names are set with different values, builds/scripts error. Set only `HEXCLAVE_*` or make both equal. - SDK consumers won’t see conflict throws; update env names to `HEXCLAVE_*` over time. <sup>Written for commit 7539fb9fbf. Summary will update on new commits.</sup> <a href="https://cubic.dev/pr/hexclave/hexclave/pull/1588?utm_source=github" target="_blank" rel="noopener noreferrer" data-no-image-dialog="true"><picture><source media="(prefers-color-scheme: dark)" srcset="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"><source media="(prefers-color-scheme: light)" srcset="https://www.cubic.dev/buttons/review-in-cubic-light.svg"><img alt="Review in cubic" src="https://www.cubic.dev/buttons/review-in-cubic-dark.svg"></picture></a> <!-- End of auto-generated description by cubic. --> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **Chores** * Migrated environment variable names from the legacy `STACK_*` prefix to the new `HEXCLAVE_*` prefix across backend, dashboard, tooling, Docker, and examples. * Updated environment/config resolution to prefer `HEXCLAVE_*`, treat empty strings as unset, and detect conflicts when both `STACK_*` and `HEXCLAVE_*` are set to different values. * Updated local emulator, server startup, and env-generation workflows to use the new names (with legacy fallback where applicable). * **Documentation** * Updated docs and code examples to reference `HEXCLAVE_*` variables. * **Tests** * Refreshed unit and e2e coverage to validate dual-read behavior, conflict detection, and empty-value handling. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-06-19 18:58:53 -07:00
Konstantin Wohlwend	9388b99c2f	Better OAuth sign-up errors	2026-06-18 11:31:25 -07:00
BilalG1	609579abab	feat(hexclave): PR 3 — native @hexclave/* source rename + delete dual-publish wiring (#1482)	2026-05-29 15:21:59 -07:00
BilalG1	f7e389809e	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
Konsti Wohlwend	c6d59d0288	Cross domain handoffs (#1458)	2026-05-21 17:15:12 -07:00
Mantra	e2dc5f5ee0	[codex] fix OAuth redirect contract (#1393) ... ## Summary - Route browser OAuth redirects through the configured `redirectMethod` instead of hardcoded `window.location` calls. - Keep OAuth redirect APIs pending after navigation starts, including custom redirect methods. - Add `cliAuthConfirm` handler URL metadata and custom-page prompt coverage. - Update SDK spec text for browser OAuth callback and `returnTo` behavior. ## Root Cause OAuth helpers previously combined URL construction with direct browser navigation. That bypassed configured redirect methods and made it too easy for public redirect APIs to resolve after navigation started. ## Impact Browser SDK consumers get consistent redirect behavior across built-in and custom navigation methods. `returnTo` is handled as the post-callback destination while the OAuth callback URL remains fixed to the configured handler route. ## Validation - `pnpm test run packages/template/src/lib/auth.test.ts` - `pnpm test run apps/e2e/tests/js/oauth.test.ts` - `pnpm -C packages/template lint` - `pnpm -C apps/e2e lint` - `pnpm -C packages/template typecheck` - `pnpm -C apps/e2e typecheck` <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Added CLI authorization confirmation page/flow for terminal-based auth. * Added optional returnTo parameter for OAuth to control post-auth redirects. * Exposed configurable redirect behavior so apps follow the chosen redirect method. * **Bug Fixes** * OAuth callback now uses app navigation/queued redirects and shows a fallback link instead of forcing location.assign. * **Tests** * Added unit and e2e tests covering OAuth URL generation, scope handling, and CLI auth confirmation. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-04-28 16:33:59 -07:00
Konstantin Wohlwend	c324ef4a12	Better error message when user info fetching fails	2026-04-13 11:10:32 -07:00
Konsti Wohlwend	5bfe1a79ce	New { type: "hosted" } for page URLs (#1261) ... Other minor redirect URL changes: - app.urls.* is now deprecated - redirectToSignOut now sets and preserves after_auth_return_to - OAuth sign-in after_auth_return_to now carries callback-return context <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **High Risk** > High risk because it changes OAuth authorization/token issuance, redirect URL validation, and introduces a new cross-domain handoff endpoint plus a DB migration linking authorization codes to refresh tokens, which can affect login/session security and reliability. > > **Overview** > Adds **hosted URL targets** for SDK `urls` resolution (new `{ type: "hosted" }`/`{ type: "handler-component" }`/`{ type: "custom" }` options), including env-driven hosted handler domain/template support and fallback routing for unknown `/handler/*` paths. > > Implements a **cross-domain OAuth PKCE handoff**: a new `/auth/oauth/cross-domain/authorize` endpoint issues one-time authorization-code redirects bound to the caller’s session refresh token; authorization codes now persist `grantedRefreshTokenId` and token issuance reuses/validates ownership of that refresh token. Redirect planning for `redirectTo*` (and OAuth callback handling) is refactored into `redirect-page-urls.ts` to preserve `after_auth_return_to` and cross-domain handoff params. > > Tightens redirect safety (e.g., `after_callback_redirect_url` is validated/whitelisted), centralizes SDK env var reads via `envVars` with lint enforcement, hardens `EventTracker` startup for partial DOM test environments, and adds unit/E2E coverage plus a demo page for manual cross-domain verification. > > <sup>Written by [Cursor Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit 9197d4f32b. This will update automatically on new commits. Configure [here](https://cursor.com/dashboard?tab=bugbot).</sup> <!-- /CURSOR_SUMMARY --> <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Cross-domain OAuth PKCE handoff flow (client + server) for hosted sign-in. * Hosted handler URL templating with local development domain suffix support. * Demo UI page to exercise hosted cross-domain sign-in/out and OAuth flows. * Authorization codes now preserve an associated refresh-token id to support cross-domain exchanges. * **Bug Fixes** * Stricter redirect-URL validation and stronger refresh-token ownership checks. * More robust event-tracker startup guards in partial DOM environments. * **Tests** * New E2E and unit tests covering cross-domain authorize, callback validation, and handoff flows. <!-- end of auto-generated comment: release notes by coderabbit.ai -->	2026-03-27 14:48:01 -07:00
Mantra	e59a70783e	Turnstile integration for fraud protection (#1239) ... Enhances sign-up process with Turnstile integration for fraud protection. Builds on top of fraud-protection-temp-emails. Made with [Cursor](https://cursor.com) <!-- This is an auto-generated comment: release notes by coderabbit.ai --> ## Summary by CodeRabbit * **New Features** * Cloudflare Turnstile bot-protection across signup/sign-in flows (including SDK JSON mode). * Email deliverability checks via Emailable. * Sign-up risk scoring with persisted risk metrics and country code tracking. * UI: country-code selector, risk-score editing in user details, users list refresh button, and Turnstile signup demo pages. * **Bug Fixes** * Use actual sign-up timestamp for reporting/metrics. * **Documentation** * Expanded knowledge base on Turnstile, risk scoring, and env configuration. <!-- end of auto-generated comment: release notes by coderabbit.ai --> --------- Co-authored-by: Konstantin Wohlwend <n2d4xc@gmail.com> Co-authored-by: BilalG1 <bg2002@gmail.com> Co-authored-by: Armaan Jain <84474476+Developing-Gamer@users.noreply.github.com> Co-authored-by: nams1570 <amanganapathy@gmail.com>	2026-03-20 21:26:45 +00:00
Konsti Wohlwend	284d85247a	Improved anonymous users (#857)	2025-08-24 11:36:01 -07:00
Konstantin Wohlwend	8717a70adc	No more instanceof KnownError	2025-05-15 12:13:19 -07:00
Zai Shi	c2cb2aac76	Add basic client lib tests (#601)	2025-04-03 20:05:44 +02:00
Zai Shi	d3cca0b73d	Vanilla JS client library (#408)	2025-02-08 02:31:03 +01:00