scriptoriumadmin/hypertwist
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
hypertwist/website/server/README.md
axiomlogicnexus 15bb11f994 Prove live website session-backed auth routes
2026-06-22 05:55:34 +00:00

5.2 KiB
Raw Blame History

HyperTwist Auth Server

Self-hosted SuperTokens auth backend for the HyperTwist website.

Responsibilities:

  • email/password sign-up and sign-in
  • optional GitHub and Google OAuth
  • session bootstrap for the browser dashboard
  • browser-to-desktop token handoff with exact-origin checks, bounded issuance, and one-time verification tokens
  • Paddle webhook endpoint with raw-body signature verification
  • verified billing-event application into first-party account/download entitlement state
  • public auth-health probe for the website with configured vs reachable core truth
  • runtime configuration diagnostics for local vs mixed vs public auth posture

Quick start

cd /home/dev/src/HyperTwist/website/server
npm install
cp .env.example .env
npm run dev

The website frontend should point at this backend through:

VITE_SUPERTOKENS_API_DOMAIN=http://localhost:3001
VITE_SUPERTOKENS_WEBSITE_DOMAIN=http://localhost:4273
VITE_AUTH_API_BASE_URL=http://localhost:3001

Important note

/api/billing/paddle/webhook now verifies the Paddle-Signature header against PADDLE_WEBHOOK_SECRET using the documented raw-body ts:h1 HMAC-SHA256 flow before it accepts the event.

The desktop-link lane is intentionally stricter than a generic session helper:

  • request origin must match the configured website origin exactly
  • token issuance is rate-limited per user
  • verification consumes the token on first successful use
  • verification now returns resolved download-entitlement posture alongside identity, plan, and role

The remaining Paddle deployment work is now configuration, not missing server ownership:

  • real production checkout URLs
  • live notification-destination secret management
  • event-specific async processing after verification

The server now also supports a small first-party entitlement store:

  • BILLING_STATE_PATH optionally relocates the persisted billing state file
  • PADDLE_PRODUCT_PLAN_MAP can map Paddle product IDs to free / operator / studio / enterprise
  • PADDLE_PRICE_PLAN_MAP can map Paddle price IDs to the same plan codes
  • if neither map is present, the verified webhook lane can still derive plan from custom_data.plan

The auth-health route now probes the configured SuperTokens core non-mutatively:

  • SUPERTOKENS_HEALTH_TIMEOUT_MS bounds the probe duration
  • /api/auth/health now distinguishes configured, reachable, and ready state
  • the protected dashboard can now show when browser fallback posture is active because the shared auth core is unreachable

Recommended public hypertwist.app posture:

  • API_DOMAIN=https://hypertwist.app
  • WEBSITE_DOMAIN=https://hypertwist.app
  • COOKIE_SECURE=true
  • real PADDLE_WEBHOOK_SECRET
  • real plan-map configuration or equivalent verified-event plan resolution

That recommended same-origin production posture is recorded in:

  • docs/ops/HYPERTWIST_WEBSITE_RUNTIME_CONFIGURATION_GUIDE_2026-06-22.md

The server now also supports a bounded first-party same-origin deployment mode:

  • if website/dist/index.html exists, the server auto-serves the built public site from ../dist
  • SPA fallback is limited to non-file public/app routes and does not intercept /api/*, /auth*, or /health
  • WEBSITE_DIST_PATH can override the bundle location when deployment layout differs
  • SERVE_STATIC_WEBSITE=true forces the server to expect a built bundle, while SERVE_STATIC_WEBSITE=false keeps api-only mode explicit
  • the example env files now carry those static-serving controls directly so deployment posture is not implicit
  • request-level tests now also prove that public/app routes serve the shell while /api/*, /auth*, /health, and missing asset paths remain unshadowed
  • a spawned bootstrap test now also proves the real src/index.ts process can start from production-shaped same-origin env, reach a ready SuperTokens core, expose green /api/auth/health, serve the built shell, accept a verified webhook, and reflect that processed billing event through live health plus the persisted entitlement file
  • the same spawned proof lane now also exercises /api/auth/me and /api/auth/desktop-link through a bounded signed test-session harness that is only active when TEST_MODE=testing and HYPERTWIST_TEST_SESSION_SECRET are explicitly set; this is validation-only, not a production auth widening

The website package now also ships a deploy-time verification command:

cd /home/dev/src/HyperTwist/website
npm run check:runtime-readiness -- --frontend-env .env --server-env server/.env --health-url https://hypertwist.app

Use --skip-live-health when only file-level env verification is possible.

Keep the example env files separated by posture:

  • website/.env.example and website/server/.env.example remain local-development defaults
  • website/.env.production.example and website/server/.env.production.example are public-posture scaffolds that still intentionally fail readiness until placeholder values are replaced

The repo now also proves that behavior directly by running the real check-runtime-readiness CLI against those production example files in test mode and asserting that placeholder launch values still fail.

The repo bootstrap CI now also validates this auth-server lane through:

  • npm ci
  • npm run type-check
  • npm test