Force-Field Console

Force-Field Protocol governance platform by Spin State Labs ("Force-Field as a Service", v0.2.2).

Renamed 2026-10-04: formerly Force-Field Portal (force-field-portal, then force-field-sandbox). Live at https://force-field-console.netlify.app, the console of the Sandbox environment; the two old *.netlify.app names are held by stub sites that 301 there. The Netlify Blobs store keeps its original name, portal.

The console provides user registration/login, API key management, tiered rate limits, Stripe billing for the paid tiers, automatic provisioning of one dedicated engine estate per paying account on Fly.io, and an authenticated API gateway that proxies /api/v1/* to the caller's estate (a Force-Field Protocol engine: thirteen FastAPI services behind one reverse-proxy origin with path prefixes such as /registry, /ledger, /delegation, /sentinel, /killswitch, /governor, /replay, /gateway, /federation, /lifecycle, /attest, /crosswalk).

Every capability is configuration-gated and reports itself honestly: /api/health exposes estate_attached, billing_configured and provisioning_configured; an endpoint whose configuration is absent answers 501 with a named error code, and the landing page renders its pricing note from those flags (see "Honest state of this deployment" below).

Tiers

Tier	Requests/min	Requests/day	Price (USD/mo)	Estate
Sandbox	10	200	0	shared sandbox estate (may be wiped)
Operator	60	5,000	49	dedicated estate on Fly.io
Sovereign	300	50,000	249	dedicated estate on Fly.io

The prices in src/lib/tiers.ts are display copy; what is actually billed is the Stripe Price referenced by STRIPE_PRICE_OPERATOR / STRIPE_PRICE_SOVEREIGN. Only the Stripe webhook writes a paid tier: a subscription in a granting status (active, trialing, past_due) with a known price sets the tier; anything else drops the account to Sandbox.

Local development

npm install
netlify dev

• npm test runs the vitest suite (unit tests; Stripe and Fly are mocked at the fetch level).
• FF_LIVE_FLY=1 npx vitest run tests/live/provision.live.test.ts runs the LIVE provisioning rehearsal: it creates a real ff-est-* app in the Fly org, drives the whole state machine against the real estate image, verifies the armed posture off-box, and destroys the app (FF_LIVE_KEEP=1 keeps it). It needs FLY_API_TOKEN (or a fly auth login on the machine) and costs a few cents. It is skipped otherwise.
• Requires Node >= 20 and the Netlify CLI (npm i -g netlify-cli).
• Set SESSION_SECRET in your environment (or a .env used by netlify dev) before exercising auth locally.

Environment variables

Variable	Required	Purpose
SESSION_SECRET	Yes	HMAC secret for HS256 session JWTs. Auth endpoints fail without it.
ESTATE_URL	No	Origin of the shared sandbox estate. Unset = the gateway returns 503 estate_not_attached for sandbox accounts.
ESTATE_SHARED_SECRET	No	Sent to the sandbox estate as x-field-auth on proxied requests, when set.
STRIPE_SECRET_KEY	For billing	Stripe secret key. Billing is configured only when all four STRIPE_* variables are set.
STRIPE_WEBHOOK_SECRET	For billing	Signing secret of the /api/billing/webhook endpoint (whsec_…).
STRIPE_PRICE_OPERATOR	For billing	Stripe Price id billed for Operator.
STRIPE_PRICE_SOVEREIGN	For billing	Stripe Price id billed for Sovereign.
STRIPE_PRICE_OPERATOR_ACCEPTED / STRIPE_PRICE_SOVEREIGN_ACCEPTED	No	Further Price ids (comma separated) that map to the tier, e.g. the old Price after a price change or another interval. Never used for Checkout. An id listed for both tiers (sale or accepted) maps to neither: billing stays on, one ALERT price_config_shared line is logged, /api/health shows price_config_shared: true, and Checkout answers 501 for a tier whose own sale Price is shared, until the variables are fixed.
FLY_API_TOKEN	For provisioning	Org-scoped Fly token (apps, volumes, machines, IPs, secrets). Provisioning is configured only when this, FLY_ORG_SLUG, FLY_ESTATE_IMAGE and ESTATE_SECRET_MASTER are all set.
FLY_ORG_SLUG	For provisioning	The Fly organization that owns customer estates.
FLY_ESTATE_IMAGE	For provisioning	The estate image to launch, e.g. registry.fly.io/force-field-sandbox:<label> — a label that was smoked and deployed on the sandbox first. Changing it (and redeploying) starts the rollout to existing estates, one per tick.

This is the beginning of the README. Read the rest at the original. Read the full README ↗