feat(backend,web): require card at trial start via stripe checkout

* feat(backend,web): require card at trial start via stripe checkout

Hosted Compass now starts signed-up users in awaiting_checkout, collects a
card through Stripe Checkout with a 7-day trial at $8/month, and enforces
read-only when payment is missing. Self-host stays fully writable when the
stripe config block is omitted. The anonymous localStorage trial is unchanged.

Co-authored-by: Tyler Dane <tyler-dane@users.noreply.github.com>

* fix(web): keep anonymous trial chip on the local clock

RootShell tests mock useAppAccess process-wide, which hid the sidebar
countdown for never-signed-up visitors. Drive that chip from
useTrialStatus again, and stop spying hasUserEverAuthenticated in
useAppAccess tests.

Co-authored-by: Tyler Dane <tyler-dane@users.noreply.github.com>

* fix(backend): close cardless trial and repeat-trial holes

Remove POST /api/billing/trial/start so hosted users cannot skip Checkout.
Grant trial_period_days only on a first subscription, send live
subscribers to the Billing Portal, apply same-second Stripe events, and
default BACKFILL_CUTOFF to the far future so existing accounts are not
grandfathered.

Co-authored-by: Tyler Dane <tyler-dane@users.noreply.github.com>

* refactor(web): derive app access from the anonymous trial hook

useAppAccess now reuses useTrialStatus for the visitor clock instead of
duplicating the localStorage effect and gate-exempt predicate.

Co-authored-by: Tyler Dane <tyler-dane@users.noreply.github.com>

* fix(backend,web): reuse portal for incomplete checkout

An incomplete Stripe subscription stays awaiting_checkout with a
subscription id; a second Checkout would open another subscription.
Send those users to the Billing Portal, hide Manage billing until a
customer exists, and idempotize the first Checkout session.

Co-authored-by: Tyler Dane <tyler-dane@users.noreply.github.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Tyler Dane <tyler-dane@users.noreply.github.com>

Author: tyler-dane

.github/workflows/_deploy-environment.yml

@@ -94,6 +94,9 @@ jobs:
           SUPERTOKENS_KEY: ${{ secrets.SUPERTOKENS_KEY }}
           SUPERTOKENS_POSTGRES_PASSWORD: ${{ secrets.SUPERTOKENS_POSTGRES_PASSWORD }}
           SUPERTOKENS_URI: ${{ secrets.SUPERTOKENS_URI }}
+          STRIPE_SECRET_KEY: ${{ (inputs.environment == 'production' || inputs.environment == 'staging-cloud') && secrets.STRIPE_SECRET_KEY || '' }}
+          STRIPE_WEBHOOK_SECRET: ${{ (inputs.environment == 'production' || inputs.environment == 'staging-cloud') && secrets.STRIPE_WEBHOOK_SECRET || '' }}
+          STRIPE_PRICE_ID: ${{ (inputs.environment == 'production' || inputs.environment == 'staging-cloud') && secrets.STRIPE_PRICE_ID || '' }}
         run: |
           echo "Deploying Compass ${RELEASE_TAG} (image version: ${IMAGE_VERSION}) to ${{ inputs.environment }}"
           # Only "production" ever runs the production runtime.nodeEnv; every
@@ -181,6 +184,13 @@ jobs:
                 "  key: \"${POSTHOG_KEY}\"" \
                 "  host: \"${POSTHOG_HOST}\""
             fi
+            if [ -n "$STRIPE_SECRET_KEY" ] && [ -n "$STRIPE_WEBHOOK_SECRET" ] && [ -n "$STRIPE_PRICE_ID" ]; then
+              printf '%s\n' \
+                'stripe:' \
+                "  secretKey: \"${STRIPE_SECRET_KEY}\"" \
+                "  webhookSecret: \"${STRIPE_WEBHOOK_SECRET}\"" \
+                "  priceId: \"${STRIPE_PRICE_ID}\""
+            fi
             printf '%s\n' \
               'sync:' \
               "  mongoUri: \"${SYNC_MONGO_URI}\"" \

bun.lock

@@ -41,6 +41,12 @@ supertokens:
 #   key: REPLACE_WITH_POSTHOG_KEY
 #   host: REPLACE_WITH_POSTHOG_HOST
 
+# stripe:
+#   secretKey: REPLACE_WITH_STRIPE_SECRET_KEY # restricted rk_test_... for staging
+#   webhookSecret: REPLACE_WITH_STRIPE_WEBHOOK_SECRET
+#   priceId: REPLACE_WITH_STRIPE_PRICE_ID
+# Omit the whole block for self-host. All three values are required together.
+
 # Compass Sync service — required. The backend exits at startup without
 # serviceUrl/internalAuthToken, and self-host runs Sync by default. mongoUri
 # MUST point at an isolated database/user that cannot read the backend's

compass.example.yaml

@@ -98,3 +98,6 @@ database and must not share the backend's database user/data.
 |---|---|---|
 | `posthog.key` | No | PostHog project key injected into the web bundle. |
 | `posthog.host` | No | PostHog host injected into the web bundle. |
+| `stripe.secretKey` | No | Stripe secret (restricted `rk_test_...` on staging). All three Stripe keys are required together; omit the whole `stripe:` block on self-host. |
+| `stripe.webhookSecret` | No | Stripe webhook signing secret. |
+| `stripe.priceId` | No | Stripe Price id for the $8/month plan. |

docs/Config/README.md

@@ -18,6 +18,7 @@ Internal documentation for engineers and agents working in the Compass repo.
 - Breakpoints, sidebar collapse, or layout at different viewport sizes: [Responsive Layout](./frontend/responsive-layout.md)
 - Local-first or storage behavior: [Offline Storage And Migrations](./features/offline-storage-and-migrations.md)
 - Backend routes and API behavior: [Backend Route Map](./backend/README.md), [Backend Request Flow](./backend/backend-request-flow.md), [Backend Error Handling](./backend/backend-error-handling.md)
+- Trial, pricing, or Stripe: [Billing And Trial](./features/billing.md)
 - A new calendar integration or Google-sync behavior: [Google Sync And SSE Flow](./features/google-sync-and-sse-flow.md), the `packages/sync` domain code directly
 
 ## Architecture And Domain

docs/README.md

@@ -25,6 +25,7 @@ Backend routes are registered from
 | Config | `packages/backend/src/config/config.routes.config.ts` | Public runtime config used by the web app. |
 | Auth | `packages/backend/src/auth/auth.routes.config.ts` | Compass-owned auth helpers and authenticated Google connect. SuperTokens also mounts recipe routes under `/api`. |
 | User | `packages/backend/src/user/user.routes.config.ts` | Profile and metadata for the active session. |
+| Billing | `packages/backend/src/billing/billing.routes.config.ts` | Session status, Checkout, Billing Portal, and unauthenticated Stripe webhook. Self-host omits Stripe keys and stays fully writable. |
 | Events | `packages/backend/src/event/event.routes.config.ts` | Event CRUD and reorder/delete helpers. |
 | Event stream | `packages/backend/src/events/events.routes.config.ts` | Authenticated SSE stream at `GET /api/events/stream`. |
 | Calendars | `packages/backend/src/calendar/calendar.routes.config.ts` | Calendar list and selection routes. |

docs/backend/README.md

@@ -15,6 +15,7 @@ Primary file:
 | Command | Implementation | Notes |
 | --- | --- | --- |
 | `bun run cli purge-user --email <address> [--apply] [--out report.json]` | `packages/scripts/src/commands/purge-user.ts` | Deletes one user's API, Sync, and SuperTokens data. Defaults to dry-run. |
+| `bun run cli backfill-billing [--apply] [--batch-size 500] [--cutoff ISO]` | `packages/scripts/src/commands/backfill-billing.ts` | Places existing accounts without billing status onto a 7-day trial. Defaults to dry-run. |
 | `bun run cli purge-corrupt-sync-events [--apply]` | `packages/scripts/src/commands/purge-corrupt-sync-events.ts` | Deletes invalid Sync event documents. Defaults to dry-run. |
 | `bun run cli refresh-connection-states [--apply]` | `packages/scripts/src/commands/refresh-connection-states.ts` | Re-derives Sync connection state. Defaults to dry-run. |
 | `bun run cli manage-failed-jobs <list\|clear\|requeue> …` | `packages/scripts/src/commands/manage-failed-jobs.ts` | Operator tooling for Sync jobs that exhausted the self-heal requeue budget. Defaults to dry-run; pass `--apply` to persist. |

docs/development/cli.md

@@ -97,6 +97,14 @@ the full picture.
 - User metadata service: `packages/backend/src/user/services/user-metadata.service.ts`
 - Mobile waitlist gate (web-only external link): `packages/web/src/components/MobileGate/MobileGate.tsx`
 
+## Billing And Trial
+
+- Shared plan/price copy: `packages/core/src/constants/billing.constants.ts`
+- Anonymous trial clock: `packages/web/src/billing/trial.storage.ts`, `packages/web/src/billing/useTrialStatus.ts`
+- Server access + paid gate: `packages/web/src/billing/useAppAccess.ts`, `packages/web/src/billing/BillingGateModal.tsx`
+- Backend billing: `packages/backend/src/billing`
+- Overview: [Billing And Trial](../features/billing.md)
+
 ## Environment And Infra
 
 - Backend config parsing: `packages/backend/src/common/constants/config.constants.ts`

docs/development/feature-file-map.md

@@ -0,0 +1,50 @@
+# Billing And Trial
+
+Hosted Compass uses Stripe Checkout (subscription mode, 7-day trial, $8/month)
+and the Stripe Billing Portal. There is no Stripe.js and no publishable key in
+the web bundle.
+
+Self-host installs omit the `stripe:` config block. `/api/config` then reports
+`billing.isConfigured: false`, the web never shows a paid gate, and event
+writes stay open.
+
+## What users see
+
+- **Never signed up:** the existing 7-day anonymous `localStorage` trial and
+  `TrialGateModal`. Unchanged.
+- **Signed up, no card yet:** `awaiting_checkout`, read-only, `BillingGateModal`
+  with Subscribe (Stripe Checkout).
+- **Trialing / active / past_due:** writable. `past_due` also shows a banner.
+- **Expired / canceled:** read-only until they subscribe again. A later
+  Checkout does not grant another trial.
+
+There is no `POST /api/billing/trial/start`. A trial only begins through
+Stripe Checkout (`trial_period_days` on the first subscription).
+
+Existing accounts are not grandfathered. `bun run cli backfill-billing` places
+rows without `billing.subscriptionStatus` onto a 7-day trial. The default
+`BACKFILL_CUTOFF` is far in the future so every such row is included; set it
+to a past instant to grandfather newer signups. Those rows have no Stripe
+subscription id, so they self-expire locally when `trialEndsAt` passes.
+
+## Staging
+
+Set `STRIPE_SECRET_KEY` (restricted `rk_test_...`), `STRIPE_WEBHOOK_SECRET`,
+and `STRIPE_PRICE_ID` on the `staging-cloud` GitHub Environment. Config-only
+deploys need `./compass restart`. Confirm `/api/config` shows
+`billing.isConfigured: true`.
+
+`staging-selfhosted` must not get those secrets — it is the live regression
+that self-host stays writable.
+
+Sales tax (`automatic_tax`) is a Stripe Dashboard decision, not a code one,
+and should be settled before production keys.
+
+## Key files
+
+- Plan/price copy: `packages/core/src/constants/billing.constants.ts`
+- Status derivation: `packages/backend/src/billing/services/billing.service.ts`
+- Checkout / portal: `packages/backend/src/billing/services/stripe.service.ts`
+- Webhook: `packages/backend/src/billing/services/billing.webhook.service.ts`
+- Write guard: `packages/backend/src/billing/billing.guard.ts`
+- Web access: `packages/web/src/billing/useAppAccess.ts`

docs/features/billing.md

@@ -6,6 +6,8 @@ Start with [Run Compass on a server](./server-guide.md). It walks through a smal
 
 If you only want to run Compass on your own computer, use the normal local development flow with Bun instead of the self-host installer.
 
+Self-host does not require Stripe. Omit the `stripe:` block so billing stays off and every account remains writable. Hosted Compass uses a 7-day trial then $8/month; see [Billing And Trial](../features/billing.md).
+
 ## Compass architecture
 
 When you self-host Compass on a server, you get a stack of small services. Only the public website and API are reachable from your browser. The databases stay private inside Docker.