@terreno/mcp 57.0.0 → 57.2.0

package/src/docs/versioned/57.1.0/how-to/configure-better-auth.md

@@ -0,0 +1,299 @@
+# Configure Better Auth
+
+Set up Better Auth as the **default** authentication provider for new Terreno apps — session-based auth with built-in social OAuth and first-class `@terreno/syncdb` integration.
+
+## Overview
+
+Better Auth is the recommended authentication system for new Terreno frontends. Register `BetterAuthApp` on the backend, set `AUTH_PROVIDER=better-auth`, and wire `createBetterAuthClient` + `generateBetterAuthSlice` on the client. Pair with `betterAuthAdapter` when using `@terreno/syncdb`.
+
+JWT/Passport remains available for legacy deployments (`AUTH_PROVIDER=jwt`). Both can run in parallel during migration.
+
+**Choose Better Auth for:**
+- New apps and greenfield screens
+- Social login (Google, GitHub, Apple)
+- Session-based authentication with `@terreno/syncdb`
+- Socket.io sync via `RealtimeApp` bearer sessions
+
+**Stay on JWT only when:**
+- You have an existing JWT deployment and are mid-migration
+- You require a fully stateless token contract with no session cookies
+- You have custom JWT payload requirements Better Auth cannot satisfy
+
+## Backend Setup
+
+### 1. Configure Environment Variables
+
+Set `AUTH_PROVIDER` to enable Better Auth:
+
+``````bash
+# Choose authentication provider
+AUTH_PROVIDER=better-auth  # or "jwt" (default)
+
+# Better Auth configuration
+BETTER_AUTH_SECRET=your-secret-key-min-32-chars
+BETTER_AUTH_URL=http://localhost:4000
+
+# Optional: Social OAuth providers
+GOOGLE_CLIENT_ID=your-google-client-id
+GOOGLE_CLIENT_SECRET=your-google-client-secret
+
+GITHUB_CLIENT_ID=your-github-client-id  
+GITHUB_CLIENT_SECRET=your-github-client-secret
+
+APPLE_CLIENT_ID=your-apple-client-id
+APPLE_CLIENT_SECRET=your-apple-client-secret
+``````
+
+### 2. Build Better Auth Configuration
+
+Create a function to build your Better Auth config:
+
+``````typescript
+import {BetterAuthConfig, AuthProvider} from "@terreno/api";
+
+const buildBetterAuthConfig = (): BetterAuthConfig | undefined => {
+  const authProvider = process.env.AUTH_PROVIDER as AuthProvider | undefined;
+
+  if (authProvider !== "better-auth") {
+    return undefined; // Use JWT auth instead
+  }
+
+  const config: BetterAuthConfig = {
+    enabled: true,
+    // Deep link schemes for mobile app redirects
+    trustedOrigins: ["yourapp://", "exp://"],
+  };
+
+  // Add Google OAuth if configured
+  if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
+    config.googleOAuth = {
+      clientId: process.env.GOOGLE_CLIENT_ID,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+    };
+  }
+
+  // Add GitHub OAuth if configured
+  if (process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET) {
+    config.githubOAuth = {
+      clientId: process.env.GITHUB_CLIENT_ID,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET,
+    };
+  }
+
+  // Add Apple OAuth if configured
+  if (process.env.APPLE_CLIENT_ID && process.env.APPLE_CLIENT_SECRET) {
+    config.appleOAuth = {
+      clientId: process.env.APPLE_CLIENT_ID,
+      clientSecret: process.env.APPLE_CLIENT_SECRET,
+    };
+  }
+
+  return config;
+};
+``````
+
+### 3. Register BetterAuthApp Plugin
+
+Use the TerrenoApp plugin system:
+
+``````typescript
+import {TerrenoApp, BetterAuthApp} from "@terreno/api";
+import {User} from "./models/user";
+
+const betterAuthConfig = buildBetterAuthConfig();
+
+const app = new TerrenoApp({
+  userModel: User,
+  // ... other options
+});
+
+// Register Better Auth plugin if configured
+if (betterAuthConfig) {
+  app.register(new BetterAuthApp({
+    config: betterAuthConfig,
+    userModel: User,
+  }));
+}
+
+const server = app.start();
+``````
+
+### 4. Update User Model
+
+Add optional Better Auth fields to your User schema:
+
+``````typescript
+import {betterAuthUserPlugin} from "@terreno/api";
+
+const userSchema = new mongoose.Schema({
+  email: {type: String, unique: true},
+  name: {type: String},
+  // ... other fields
+});
+
+// Adds: betterAuthId, oauthProvider
+userSchema.plugin(betterAuthUserPlugin);
+``````
+
+## Frontend Setup
+
+### 1. Create Better Auth Client
+
+``````typescript
+import {createBetterAuthClient} from "@terreno/rtk";
+
+export const authClient = createBetterAuthClient({
+  baseURL: process.env.EXPO_PUBLIC_API_URL || "http://localhost:4000",
+});
+``````
+
+### 2. Add Session Redux Slice
+
+``````typescript
+import {generateBetterAuthSlice} from "@terreno/rtk";
+import {configureStore} from "@reduxjs/toolkit";
+import {authClient} from "./authClient";
+
+const {sessionReducer, sessionMiddleware} = generateBetterAuthSlice(authClient);
+
+export const store = configureStore({
+  reducer: {
+    session: sessionReducer,
+    // ... other reducers
+  },
+  middleware: (getDefault) => getDefault().concat(sessionMiddleware),
+});
+``````
+
+### 3. Add Social Login UI
+
+Use the SocialLoginButton component:
+
+``````typescript
+import {SocialLoginButton, Box} from "@terreno/ui";
+import {authClient} from "@/store/authClient";
+
+const LoginScreen = () => {
+  return (
+    <Box padding={4} gap={3}>
+      <SocialLoginButton
+        provider="google"
+        onPress={async () => {
+          await authClient.signIn.social({
+            provider: "google",
+            callbackURL: "yourapp://auth/callback",
+          });
+        }}
+      />
+      
+      <SocialLoginButton
+        provider="github"
+        onPress={async () => {
+          await authClient.signIn.social({
+            provider: "github",
+            callbackURL: "yourapp://auth/callback",
+          });
+        }}
+      />
+      
+      <SocialLoginButton
+        provider="apple"
+        onPress={async () => {
+          await authClient.signIn.social({
+            provider: "apple",
+            callbackURL: "yourapp://auth/callback",
+          });
+        }}
+      />
+    </Box>
+  );
+};
+``````
+
+## OAuth Provider Setup
+
+### Google OAuth
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select existing
+3. Enable Google+ API
+4. Create OAuth 2.0 credentials
+5. Add authorized redirect URIs:
+   - `http://localhost:4000/api/auth/callback/google` (development)
+   - `https://yourapp.com/api/auth/callback/google` (production)
+6. Copy Client ID and Client Secret to `.env`
+
+### GitHub OAuth
+
+1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
+2. Create a new OAuth App
+3. Set Authorization callback URL:
+   - `http://localhost:4000/api/auth/callback/github` (development)
+   - `https://yourapp.com/api/auth/callback/github` (production)
+4. Copy Client ID and generate Client Secret
+5. Add to `.env`
+
+### Apple Sign In
+
+1. Go to [Apple Developer Console](https://developer.apple.com/)
+2. Create a new Services ID
+3. Configure Sign in with Apple
+4. Add return URLs (similar to above)
+5. Generate private key and download
+6. Copy Service ID and Key to `.env`
+
+## Generated Endpoints
+
+When Better Auth is enabled, these endpoints are available:
+
+- `POST /api/auth/signup/email` — Email/password signup
+- `POST /api/auth/signin/email` — Email/password signin
+- `GET /api/auth/signin/google` — Initiate Google OAuth
+- `GET /api/auth/signin/github` — Initiate GitHub OAuth
+- `GET /api/auth/signin/apple` — Initiate Apple Sign In
+- `GET /api/auth/callback/{provider}` — OAuth callback handler
+- `POST /api/auth/signout` — Sign out current session
+- `GET /api/auth/session` — Get current session
+
+## Troubleshooting
+
+### "BETTER_AUTH_SECRET is not set"
+
+Ensure you've set both `AUTH_PROVIDER=better-auth` and `BETTER_AUTH_SECRET` in your environment variables.
+
+### OAuth redirect mismatch
+
+Verify the callback URLs in your OAuth provider settings match your `BETTER_AUTH_URL` + `/api/auth/callback/{provider}`.
+
+### Session not persisting
+
+Check that `trustedOrigins` in your Better Auth config includes your app's deep link scheme (e.g., `"yourapp://"`).
+
+### Social login opens browser but doesn't redirect back
+
+Ensure your mobile app has the proper deep link configuration in `app.json`:
+
+``````json
+{
+  "expo": {
+    "scheme": "yourapp"
+  }
+}
+``````
+
+## Migration from JWT Auth
+
+Better Auth runs **in parallel** with JWT auth. You don't need to migrate existing users immediately:
+
+1. Set `AUTH_PROVIDER=better-auth`
+2. Keep existing JWT endpoints available (they still work)
+3. New users can sign up via Better Auth
+4. Existing users continue using JWT tokens
+5. Optionally add migration logic to link accounts
+
+## Learn More
+
+- [Authentication Architecture](../explanation/authentication.md)
+- [@terreno/api Reference](../reference/api.md#better-auth)
+- [@terreno/rtk Reference (legacy)](../reference/legacy/rtk.md#better-auth)
+- [Better Auth Documentation](https://better-auth.com/)

package/src/docs/versioned/57.1.0/how-to/deploy-backend-to-cloud-run.md

@@ -0,0 +1,115 @@
+# Deploy backend to Cloud Run
+
+Deploy a Terreno `@terreno/api` backend (for example `example-backend`) to Google Cloud Run with Secret Manager.
+
+Replace placeholders: `$PROJECT_ID`, `$REGION`, `$SERVICE_NAME`, `$REPOSITORY`.
+
+## Prerequisites
+
+- [gcloud CLI](https://cloud.google.com/sdk/docs/install) installed and authenticated
+- GCP project with billing enabled
+- MongoDB Atlas cluster (or other replica set) — [deployment baseline](../explanation/deployment-baseline.md)
+- Docker (local build) or Cloud Build
+
+Enable APIs:
+
+```bash
+gcloud services enable run.googleapis.com artifactregistry.googleapis.com secretmanager.googleapis.com --project="$PROJECT_ID"
+```
+
+## 1. Create Artifact Registry
+
+```bash
+gcloud artifacts repositories create "$REPOSITORY" \
+  --repository-format=docker \
+  --location="$REGION" \
+  --project="$PROJECT_ID"
+```
+
+## 2. Build and push the image
+
+From the **repository root** (the Dockerfile expects the monorepo context):
+
+```bash
+docker build -f example-backend/Dockerfile -t "$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/$SERVICE_NAME:latest" .
+docker push "$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/$SERVICE_NAME:latest"
+```
+
+## 3. Create secrets
+
+Create Secret Manager secrets (values added out of band):
+
+```bash
+for name in mongodb-uri token-secret token-issuer refresh-token-secret session-secret; do
+  gcloud secrets create "$SERVICE_NAME-$name" --project="$PROJECT_ID" --replication-policy=automatic
+done
+```
+
+Add secret values (example for MongoDB URI):
+
+```bash
+echo -n 'mongodb+srv://user:pass@cluster.example/terreno?retryWrites=true&w=majority' | \
+  gcloud secrets versions add "$SERVICE_NAME-mongodb-uri" --data-file=- --project="$PROJECT_ID"
+```
+
+Repeat for `TOKEN_SECRET`, `TOKEN_ISSUER`, `REFRESH_TOKEN_SECRET`, and `SESSION_SECRET`.
+
+For Better Auth, also create `better-auth-secret` and set `AUTH_PROVIDER=better-auth` plus `BETTER_AUTH_URL` at deploy time. See [Configure Better Auth](configure-better-auth.md).
+
+## 4. Runtime service account
+
+```bash
+gcloud iam service-accounts create "$SERVICE_NAME-runtime" --project="$PROJECT_ID"
+
+gcloud projects add-iam-policy-binding "$PROJECT_ID" \
+  --member="serviceAccount:$SERVICE_NAME-runtime@$PROJECT_ID.iam.gserviceaccount.com" \
+  --role="roles/secretmanager.secretAccessor"
+```
+
+Grant object access on your uploads bucket separately if using GCS file storage.
+
+## 5. Deploy to Cloud Run
+
+```bash
+gcloud run deploy "$SERVICE_NAME" \
+  --image="$REGION-docker.pkg.dev/$PROJECT_ID/$REPOSITORY/$SERVICE_NAME:latest" \
+  --region="$REGION" \
+  --project="$PROJECT_ID" \
+  --platform=managed \
+  --port=3000 \
+  --session-affinity \
+  --timeout=3600 \
+  --min-instances=1 \
+  --allow-unauthenticated \
+  --service-account="$SERVICE_NAME-runtime@$PROJECT_ID.iam.gserviceaccount.com" \
+  --set-secrets="MONGO_URI=$SERVICE_NAME-mongodb-uri:latest,TOKEN_SECRET=$SERVICE_NAME-token-secret:latest,TOKEN_ISSUER=$SERVICE_NAME-token-issuer:latest,REFRESH_TOKEN_SECRET=$SERVICE_NAME-refresh-token-secret:latest,SESSION_SECRET=$SERVICE_NAME-session-secret:latest" \
+  --set-env-vars="NODE_ENV=production"
+```
+
+Adjust `min-instances` to `0` for dev sandboxes (websockets will churn on cold start).
+
+## 6. Verify
+
+```bash
+SERVICE_URL=$(gcloud run services describe "$SERVICE_NAME" --region="$REGION" --project="$PROJECT_ID" --format='value(status.url)')
+curl -s "$SERVICE_URL/health" | jq .
+```
+
+Expect `"healthy": true`.
+
+## Production constraints
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Websockets disconnect every few requests | No session affinity on Cloud Run | Add `--session-affinity` |
+| Socket connections drop after ~5 minutes | Default request timeout (300s) | Raise `--timeout` (for example `3600`) |
+| Live feature flags / realtime never update; log mentions replica set | MongoDB is standalone, not a replica set | Use Atlas or `replSet` — change streams required (`feature-flags/src/featureFlagsApp.ts`) |
+| First request after idle is slow; sockets reconnect constantly | Scaled to zero | Set `--min-instances=1` for user-facing services |
+| Browser API calls blocked by CORS | `corsOrigin` / Better Auth `trustedOrigins` missing web origin | Add your CDN URL to backend CORS and auth config |
+
+## Related
+
+- [Deployment baseline](../explanation/deployment-baseline.md)
+- [Environment variables](../reference/environment-variables.md)
+- [Deploy web to GCS + CDN](deploy-web-to-gcs-cdn.md)
+- [GCP architecture](../explanation/deployment-architecture-gcp.md)

package/src/docs/versioned/57.1.0/how-to/deploy-to-gcp.md

@@ -0,0 +1,36 @@
+# Deploy to Google Cloud Platform
+
+Deploy a Terreno full-stack app to GCP: Cloud Run for the backend, GCS + Cloud CDN for the static web export.
+
+## Before you start
+
+Read the [deployment baseline](../explanation/deployment-baseline.md) — seven requirements (replica-set MongoDB, auth secrets, build-time `EXPO_PUBLIC_API_URL`, and more) apply to every provider.
+
+## Guides
+
+| Guide | What it covers |
+|-------|----------------|
+| [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md) | Container image, Secret Manager, Cloud Run with session affinity |
+| [Deploy web to GCS + CDN](deploy-web-to-gcs-cdn.md) | Static web export, bucket + CDN setup, cache invalidation |
+| [Build for web](build-for-web.md) | Export command, `EXPO_PUBLIC_API_URL`, local verification |
+
+## Architecture
+
+[GCP deployment architecture](../explanation/deployment-architecture-gcp.md) — topology diagram, component roles, and tradeoffs (Cloud Run vs GKE, static vs SSR).
+
+## Scripts
+
+- [`scripts/setup-gcs-hosting.sh`](https://github.com/FlourishHealth/terreno/blob/master/scripts/setup-gcs-hosting.sh) — parameterized GCS + CDN provisioning for one site
+
+## Environment variables
+
+[Environment variables reference](../reference/environment-variables.md) — full list of backend and client config.
+
+## Legacy Flourish deployment
+
+Flourish-specific infrastructure (hardcoded project IDs, CI deploy workflows) lives in `infra/flourish/` and the existing `demo-deploy.yml` / `frontend-example-deploy.yml` workflows. New deployments should follow the generalized guides above with your own `$PROJECT_ID` and bucket names.
+
+## Related
+
+- [Environment variables](../reference/environment-variables.md)
+- [Deployment baseline](../explanation/deployment-baseline.md)

package/src/docs/versioned/57.1.0/how-to/deploy-web-to-gcs-cdn.md

@@ -0,0 +1,183 @@
+# Deploy web to GCS + CDN
+
+Host a static Terreno web export on Google Cloud Storage with Cloud CDN.
+
+Replace placeholders: `$PROJECT_ID`, `$REGION`, `$WEB_BUCKET`, `$SITE_NAME`, `$DOMAIN`.
+
+## Prerequisites
+
+- [gcloud CLI](https://cloud.google.com/sdk/docs/install) installed and authenticated
+- Backend deployed and CORS configured — see [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md)
+- [Build for web](build-for-web.md) completed with the correct `EXPO_PUBLIC_API_URL`
+
+## 1. Build the web bundle
+
+Set the API URL **before** export — it is inlined into the bundle:
+
+```bash
+cd example-frontend
+EXPO_PUBLIC_API_URL=https://api.example.com bun run export
+```
+
+The export script is `bun expo export --platform web` (see `example-frontend/package.json`).
+
+Output is in `dist/`.
+
+## 2. Enable the Compute Engine API
+
+Cloud CDN and its global load-balancing resources require the Compute Engine API:
+
+```bash
+gcloud services enable compute.googleapis.com --project="$PROJECT_ID"
+```
+
+## 3. Create the GCS bucket
+
+```bash
+gsutil mb -p "$PROJECT_ID" -l "$REGION" "gs://$WEB_BUCKET/"
+```
+
+## 4. Allow public object reads
+
+Cloud CDN must be able to serve the bucket's objects to unauthenticated visitors:
+
+```bash
+gsutil iam ch allUsers:objectViewer "gs://$WEB_BUCKET"
+```
+
+Do not grant `allUsers` a write role such as `objectAdmin`.
+
+## 5. Configure SPA routing
+
+Client-side routes require `index.html` for unknown paths:
+
+```bash
+gsutil web set -e index.html "gs://$WEB_BUCKET"
+```
+
+Do not set `MainPageSuffix` — GCS 301 redirects break client-side routing.
+
+## 6. Upload the build
+
+```bash
+gsutil -m -h "Cache-Control:public, max-age=31536000, immutable" \
+  rsync -r -d -x '.*\.html$' \
+  dist/ "gs://$WEB_BUCKET/"
+
+gsutil -h "Cache-Control:no-cache, no-store, must-revalidate" \
+  cp dist/index.html "gs://$WEB_BUCKET/index.html"
+```
+
+## 7. Create HTTPS CDN resources
+
+The load balancer serves the bucket over HTTPS only. A Google-managed certificate secures
+the domain:
+
+```bash
+# Backend bucket (CDN-enabled)
+gcloud compute backend-buckets create "${SITE_NAME}-backend" \
+  --gcs-bucket-name="$WEB_BUCKET" \
+  --enable-cdn \
+  --no-negative-caching \
+  --project="$PROJECT_ID"
+
+# URL map
+gcloud compute url-maps create "${SITE_NAME}-url-map" \
+  --default-backend-bucket="${SITE_NAME}-backend" \
+  --project="$PROJECT_ID"
+
+# Static IP
+gcloud compute addresses create "${SITE_NAME}-ip" --global --project="$PROJECT_ID"
+
+# Managed TLS certificate
+gcloud compute ssl-certificates create "${SITE_NAME}-cert" \
+  --domains="$DOMAIN" \
+  --global \
+  --project="$PROJECT_ID"
+
+# HTTPS proxy
+gcloud compute target-https-proxies create "${SITE_NAME}-https-proxy" \
+  --url-map="${SITE_NAME}-url-map" \
+  --ssl-certificates="${SITE_NAME}-cert" \
+  --project="$PROJECT_ID"
+
+# HTTPS forwarding rule
+gcloud compute forwarding-rules create "${SITE_NAME}-https-forwarding-rule" \
+  --address="${SITE_NAME}-ip" \
+  --target-https-proxy="${SITE_NAME}-https-proxy" \
+  --global \
+  --ports=443 \
+  --project="$PROJECT_ID"
+```
+
+## 8. Redirect HTTP to HTTPS
+
+Port 80 should redirect rather than serve the bundle. Without a listener there at all, `http://$DOMAIN` fails to connect instead of sending visitors to the secure URL.
+
+`gcloud` exposes redirect behavior only through an imported spec, not through `url-maps create` flags:
+
+```bash
+gcloud compute url-maps import "${SITE_NAME}-http-redirect-url-map" \
+  --global --project="$PROJECT_ID" --source=/dev/stdin <<SPEC
+name: ${SITE_NAME}-http-redirect-url-map
+defaultUrlRedirect:
+  httpsRedirect: true
+  redirectResponseCode: MOVED_PERMANENTLY_DEFAULT
+SPEC
+
+gcloud compute target-http-proxies create "${SITE_NAME}-http-proxy" \
+  --url-map="${SITE_NAME}-http-redirect-url-map" \
+  --project="$PROJECT_ID"
+
+gcloud compute forwarding-rules create "${SITE_NAME}-forwarding-rule" \
+  --address="${SITE_NAME}-ip" \
+  --target-http-proxy="${SITE_NAME}-http-proxy" \
+  --global \
+  --ports=80 \
+  --project="$PROJECT_ID"
+```
+
+Port 80 now only ever returns a 301; the bundle itself is served exclusively over TLS.
+
+Or run the parameterized script, which provisions steps 7 and 8 in one pass:
+
+```bash
+./scripts/setup-gcs-hosting.sh \
+  --project "$PROJECT_ID" \
+  --site-name "$SITE_NAME" \
+  --bucket "$WEB_BUCKET" \
+  --domain "$DOMAIN"
+```
+
+## 9. Point DNS and wait for the certificate
+
+```bash
+gcloud compute addresses describe "${SITE_NAME}-ip" --global \
+  --project="$PROJECT_ID" --format='value(address)'
+```
+
+Create an A record for `$DOMAIN` pointing at that IP. Managed certificates only begin provisioning once DNS resolves to the load balancer, and can take up to about an hour to become active:
+
+```bash
+gcloud compute ssl-certificates describe "${SITE_NAME}-cert" --global \
+  --project="$PROJECT_ID" --format='value(managed.status)'
+```
+
+Wait for `ACTIVE` before sending traffic. Still `PROVISIONING` after an hour usually means the A record does not resolve to the reserved IP.
+
+## 10. Invalidate cache after deploy
+
+```bash
+gcloud compute url-maps invalidate-cdn-cache "${SITE_NAME}-url-map" \
+  --path "/*" --async --project="$PROJECT_ID"
+```
+
+## Static-only path
+
+This guide hosts the `expo export -p web` output as static files. Server-rendered web (SSR, API routes) requires Expo SDK ≥ 55 — see [Web SSR and admin SPA](https://github.com/FlourishHealth/terreno/blob/master/docs/implementationPlans/web-ssr-and-admin-spa.md).
+
+## Related
+
+- [Build for web](build-for-web.md)
+- [Deploy backend to Cloud Run](deploy-backend-to-cloud-run.md)
+- [GCP architecture](../explanation/deployment-architecture-gcp.md)