mirror of
https://github.com/stack-auth/stack.git
synced 2026-06-30 21:01:54 +08:00
38ae913fc9
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
## 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 -->
139 lines
7.4 KiB
Plaintext
139 lines
7.4 KiB
Plaintext
NEXT_PUBLIC_HEXCLAVE_API_URL=http://localhost:${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}02
|
|
NEXT_PUBLIC_HEXCLAVE_DASHBOARD_URL=http://localhost:${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}01
|
|
NEXT_PUBLIC_HEXCLAVE_HOSTED_HANDLER_DOMAIN_SUFFIX=.localhost:${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}09
|
|
NEXT_PUBLIC_HEXCLAVE_IS_LOCAL_EMULATOR=false
|
|
HEXCLAVE_SERVER_SECRET=23-wuNpik0gIW4mruTz25rbIvhuuvZFrLOLtL7J4tyo
|
|
|
|
HEXCLAVE_CHANGELOG_URL=https://raw.githubusercontent.com/hexclave/hexclave/refs/heads/dev/CHANGELOG.md
|
|
|
|
HEXCLAVE_SEED_ENABLE_DUMMY_PROJECT=true
|
|
HEXCLAVE_SEED_INTERNAL_PROJECT_SIGN_UP_ENABLED=true
|
|
HEXCLAVE_SEED_INTERNAL_PROJECT_OTP_ENABLED=true
|
|
HEXCLAVE_SEED_INTERNAL_PROJECT_ALLOW_LOCALHOST=true
|
|
HEXCLAVE_SEED_INTERNAL_PROJECT_OAUTH_PROVIDERS=github,spotify,google,microsoft
|
|
HEXCLAVE_SEED_INTERNAL_PROJECT_USER_GITHUB_ID=admin@example.com
|
|
HEXCLAVE_SEED_INTERNAL_PROJECT_USER_INTERNAL_ACCESS=true
|
|
HEXCLAVE_INTERNAL_PROJECT_PUBLISHABLE_CLIENT_KEY=this-publishable-client-key-is-for-local-development-only
|
|
HEXCLAVE_INTERNAL_PROJECT_SECRET_SERVER_KEY=this-secret-server-key-is-for-local-development-only
|
|
HEXCLAVE_SEED_INTERNAL_PROJECT_SUPER_SECRET_ADMIN_KEY=this-super-secret-admin-key-is-for-local-development-only
|
|
|
|
HEXCLAVE_OAUTH_MOCK_URL=http://localhost:${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}14
|
|
HEXCLAVE_TURNSTILE_SITEVERIFY_URL=http://localhost:${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}14/turnstile/siteverify
|
|
|
|
# Cloudflare Turnstile test keys — always-pass widgets, no real challenges
|
|
# See https://developers.cloudflare.com/turnstile/troubleshooting/testing/
|
|
NEXT_PUBLIC_HEXCLAVE_BOT_CHALLENGE_SITE_KEY=1x00000000000000000000AA
|
|
NEXT_PUBLIC_HEXCLAVE_BOT_CHALLENGE_INVISIBLE_SITE_KEY=1x00000000000000000000BB
|
|
HEXCLAVE_TURNSTILE_SECRET_KEY=1x0000000000000000000000000000000AA
|
|
# Set to true to disable Turnstile entirely in local development.
|
|
# This skips invisible/visible bot challenge flow and removes the Turnstile risk penalty.
|
|
HEXCLAVE_DISABLE_BOT_CHALLENGE=false
|
|
# Default behavior is to block sign-up if the visible challenge cannot be completed.
|
|
# Flip this only when you intentionally want local sign-up to continue during Turnstile outages.
|
|
HEXCLAVE_ALLOW_SIGN_UP_ON_VISIBLE_BOT_CHALLENGE_FAILURE=false
|
|
|
|
HEXCLAVE_GITHUB_CLIENT_ID=MOCK
|
|
HEXCLAVE_GITHUB_CLIENT_SECRET=MOCK
|
|
HEXCLAVE_GOOGLE_CLIENT_ID=MOCK
|
|
HEXCLAVE_GOOGLE_CLIENT_SECRET=MOCK
|
|
HEXCLAVE_MICROSOFT_CLIENT_ID=MOCK
|
|
HEXCLAVE_MICROSOFT_CLIENT_SECRET=MOCK
|
|
HEXCLAVE_SPOTIFY_CLIENT_ID=MOCK
|
|
HEXCLAVE_SPOTIFY_CLIENT_SECRET=MOCK
|
|
|
|
HEXCLAVE_ALLOW_SHARED_OAUTH_ACCESS_TOKENS=true
|
|
|
|
# Default to enforcing plan limits in local dev so behavior matches prod.
|
|
# Flip to "true" to bypass every Stack-Auth-internal plan-limit enforcement
|
|
# site (e.g. session_replays, analytics_events, emails_per_month). See
|
|
# apps/backend/src/lib/plan-entitlements.ts:arePlanLimitsEnforced.
|
|
HEXCLAVE_DISABLE_PLAN_LIMITS=false
|
|
|
|
HEXCLAVE_DATABASE_CONNECTION_STRING=postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}28/stackframe
|
|
HEXCLAVE_DATABASE_REPLICA_CONNECTION_STRING=postgres://postgres:PASSWORD-PLACEHOLDER--uqfEC1hmmv@localhost:${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}34/stackframe
|
|
HEXCLAVE_DATABASE_REPLICATION_WAIT_STRATEGY=pg-stat-replication
|
|
|
|
HEXCLAVE_EMAIL_HOST=127.0.0.1
|
|
HEXCLAVE_EMAIL_PORT=${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}29
|
|
HEXCLAVE_EMAIL_SECURE=false
|
|
HEXCLAVE_EMAIL_USERNAME="does not matter, ignored by Inbucket"
|
|
HEXCLAVE_EMAIL_PASSWORD="does not matter, ignored by Inbucket"
|
|
HEXCLAVE_EMAIL_SENDER=noreply@example.com
|
|
|
|
HEXCLAVE_ACCESS_TOKEN_EXPIRATION_TIME=60s
|
|
|
|
HEXCLAVE_DEFAULT_EMAIL_CAPACITY_PER_HOUR=100000
|
|
|
|
HEXCLAVE_SVIX_SERVER_URL=http://localhost:${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}13
|
|
HEXCLAVE_SVIX_API_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2NTUxNDA2MzksImV4cCI6MTk3MDUwMDYzOSwibmJmIjoxNjU1MTQwNjM5LCJpc3MiOiJzdml4LXNlcnZlciIsInN1YiI6Im9yZ18yM3JiOFlkR3FNVDBxSXpwZ0d3ZFhmSGlyTXUifQ.En8w77ZJWbd0qrMlHHupHUB-4cx17RfzFykseg95SUk
|
|
|
|
# Trusted reverse proxy for reading real client IP addresses.
|
|
# Set to "vercel", "cloudflare", or leave empty/unset for no proxy trust.
|
|
HEXCLAVE_TRUSTED_PROXY=
|
|
|
|
HEXCLAVE_ARTIFICIAL_DEVELOPMENT_DELAY_MS=500
|
|
|
|
HEXCLAVE_ENABLE_HARDCODED_PASSKEY_CHALLENGE_FOR_TESTING=yes
|
|
|
|
HEXCLAVE_INTEGRATION_CLIENTS_CONFIG='[{"client_id": "neon-local", "client_secret": "neon-local-secret", "id_token_signed_response_alg": "ES256", "redirect_uris": ["http://localhost:30000/api/v2/identity/authorize", "http://localhost:30000/api/v2/auth/authorize"]}, {"client_id": "custom-local", "client_secret": "custom-local-secret", "id_token_signed_response_alg": "ES256", "redirect_uris": ["http://localhost:30000/api/v2/identity/authorize", "http://localhost:30000/api/v2/auth/authorize"]}]'
|
|
CRON_SECRET=mock_cron_secret
|
|
HEXCLAVE_FREESTYLE_API_KEY=mock_stack_freestyle_key
|
|
HEXCLAVE_VERCEL_SANDBOX_TOKEN=vercel_sandbox_disabled_for_local_development
|
|
HEXCLAVE_OPENAI_API_KEY=mock_openai_api_key
|
|
HEXCLAVE_STRIPE_SECRET_KEY=sk_test_mockstripekey
|
|
HEXCLAVE_STRIPE_WEBHOOK_SECRET=mock_stripe_webhook_secret
|
|
HEXCLAVE_OPENROUTER_API_KEY=FORWARD_TO_PRODUCTION
|
|
HEXCLAVE_FEEDBACK_MODE=FORWARD_TO_PRODUCTION
|
|
HEXCLAVE_MINTLIFY_MCP_URL=https://stackauth-e0affa27.mintlify.app/mcp
|
|
# Email monitor configuration for tests
|
|
HEXCLAVE_EMAIL_MONITOR_VERIFICATION_CALLBACK_URL=http://localhost:8101/handler/email-verification
|
|
HEXCLAVE_EMAIL_MONITOR_PROJECT_ID=internal
|
|
HEXCLAVE_EMAIL_MONITOR_PUBLISHABLE_CLIENT_KEY=this-publishable-client-key-is-for-local-development-only
|
|
HEXCLAVE_EMAIL_MONITOR_RESEND_EMAIL_DOMAIN=stack-generated.example.com
|
|
HEXCLAVE_EMAIL_MONITOR_RESEND_EMAIL_API_KEY=this-is-a-fake-key
|
|
HEXCLAVE_EMAIL_MONITOR_INBUCKET_API_URL=http://localhost:${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}05
|
|
HEXCLAVE_EMAIL_MONITOR_USE_INBUCKET=true
|
|
HEXCLAVE_EMAIL_MONITOR_SECRET_TOKEN=this-secret-token-is-for-local-development-only
|
|
|
|
HEXCLAVE_EMAILABLE_API_KEY=
|
|
|
|
HEXCLAVE_INTERNAL_FEEDBACK_RECIPIENTS=team@hexclave.com
|
|
|
|
# S3 Configuration for local development using s3mock
|
|
HEXCLAVE_S3_ENDPOINT=http://localhost:${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}21
|
|
HEXCLAVE_S3_REGION=us-east-1
|
|
HEXCLAVE_S3_ACCESS_KEY_ID=s3mockroot
|
|
HEXCLAVE_S3_SECRET_ACCESS_KEY=s3mockroot
|
|
HEXCLAVE_S3_BUCKET=stack-storage
|
|
HEXCLAVE_S3_PRIVATE_BUCKET=stack-storage-private
|
|
|
|
# AWS region defaults to LocalStack
|
|
HEXCLAVE_AWS_REGION=us-east-1
|
|
HEXCLAVE_AWS_KMS_ENDPOINT=http://localhost:${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}24
|
|
HEXCLAVE_AWS_ACCESS_KEY_ID=test
|
|
HEXCLAVE_AWS_SECRET_ACCESS_KEY=test
|
|
|
|
# Upstash defaults to one of the pre-build test users of the local emulator
|
|
HEXCLAVE_QSTASH_URL=http://localhost:${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}25
|
|
HEXCLAVE_QSTASH_TOKEN=eyJVc2VySUQiOiJkZWZhdWx0VXNlciIsIlBhc3N3b3JkIjoiZGVmYXVsdFBhc3N3b3JkIn0=
|
|
HEXCLAVE_QSTASH_CURRENT_SIGNING_KEY=sig_7kYjw48mhY7kAjqNGcy6cr29RJ6r
|
|
HEXCLAVE_QSTASH_NEXT_SIGNING_KEY=sig_5ZB6DVzB1wjE8S6rZ7eenA8Pdnhs
|
|
|
|
# MCP review tool (SpacetimeDB)
|
|
HEXCLAVE_SPACETIMEDB_URI=ws://localhost:${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}39
|
|
HEXCLAVE_SPACETIMEDB_DB_NAME=stack-auth-llm
|
|
HEXCLAVE_MCP_LOG_TOKEN=change-me
|
|
|
|
# Clickhouse
|
|
HEXCLAVE_CLICKHOUSE_URL=http://localhost:${NEXT_PUBLIC_HEXCLAVE_PORT_PREFIX:-81}36
|
|
HEXCLAVE_CLICKHOUSE_ADMIN_USER=stackframe
|
|
HEXCLAVE_CLICKHOUSE_ADMIN_PASSWORD=PASSWORD-PLACEHOLDER--9gKyMxJeMx
|
|
HEXCLAVE_CLICKHOUSE_EXTERNAL_PASSWORD=PASSWORD-PLACEHOLDER--EZeHscBMzE
|
|
|
|
# Managed emails
|
|
HEXCLAVE_RESEND_API_KEY=mock_resend_api_key
|
|
HEXCLAVE_RESEND_WEBHOOK_SECRET=mock_resend_webhook_secret
|
|
HEXCLAVE_DNSIMPLE_API_TOKEN=mock_dnsimple_api_token
|
|
HEXCLAVE_DNSIMPLE_ACCOUNT_ID=mock_dnsimple_account_id
|
|
HEXCLAVE_DNSIMPLE_API_BASE_URL=https://api.dnsimple.com/v2
|