@terreno/mcp 57.14.0 → 57.16.1

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

@@ -0,0 +1,326 @@
+# 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;
+};
+``````
+
+Set `publicAppUrl`, `sendMail`, and `renderAuthMail` from `@terreno/comms` so password-reset and
+email-verification mail match the JWT recovery templates. The hooks throw 501 and do not send when
+`publicAppUrl` is missing. JWT `POST /auth/resetPassword` updates the Better Auth password and
+deletes Better Auth sessions when this plugin is registered. Better Auth password reset updates
+the JWT password and `tokenEpoch` for the matching app User so dual-enrolled accounts cannot keep
+the old passport hash.
+
+```typescript
+import {getCommsService, renderAuthMail} from "@terreno/comms";
+
+const config: BetterAuthConfig = {
+  enabled: true,
+  publicAppUrl: process.env.FRONTEND_URL || "http://localhost:8082",
+  renderAuthMail,
+  sendMail: async (message) => {
+    await getCommsService().sendMail(message);
+  },
+  // ...
+};
+```
+
+Throwaway in-process seed apps (CLI / container smoke tests that call Better Auth
+sign-up many times) should set `disableRateLimit: true` on that instance only.
+Better Auth enables its limiter in production, which 429s the fourth seeded user.
+
+### 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
+
+`syncBetterAuthUser` creates the app `User` on the first authenticated request after Better Auth sign-up. Declare `betterAuthId` on that schema. Declare `oauthProvider` only if the app uses social OAuth.
+
+Email/password sync does **not** write `oauthProvider`. A `strict: "throw"` schema that omits the field stays valid. Social login still passes a provider string and requires the field.
+
+``````typescript
+const userSchema = new mongoose.Schema(
+  {
+    email: {type: String, unique: true},
+    name: {type: String},
+    betterAuthId: {index: true, sparse: true, type: String},
+    // Required only when using Google, GitHub, or Apple:
+    // oauthProvider: {type: String},
+  },
+  {strict: "throw"}
+);
+``````
+
+## 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.15.0/how-to/connect-mcp-service-token.md

@@ -0,0 +1,110 @@
+# Connect an MCP client with a service token
+
+Mint a personal `mcp_…` Bearer key, then paste the MCP URL and key into Perplexity, Cursor, VS Code, or Claude Code.
+
+This is the **static-key** path for the consumer app's `POST /mcp`. It is not the hosted `@terreno/mcp` codegen server. For exposing tools, see [Expose MCP tools](expose-mcp-tools.md). Interactive OAuth for remote clients is a separate plan ([app MCP server](../implementationPlans/app-mcp-server.md)); do not send these keys in a query string.
+
+## 1. Enable the flag
+
+```typescript
+new TerrenoApp({
+  userModel: User,
+  mcpServiceTokens: {
+    enabled: true,
+    publicMcpUrl: process.env.PUBLIC_API_URL,
+  },
+});
+```
+
+`mcpServiceTokens: true` is the same as `{enabled: true}`. Off (omitted or `enabled: false`) does not mount `/mcp/service-tokens` and does not accept `mcp_` Bearer credentials on `/mcp`.
+
+Pass `publicMcpUrl` so create responses include a copy-paste MCP URL (`…/mcp` is appended when missing). The example backend uses `PUBLIC_API_URL` or `BETTER_AUTH_URL`.
+
+## 2. Mint a token (Settings)
+
+1. Sign in to the example app.
+2. Open **Profile** → **MCP connections** (`/settings/mcp`).
+3. Enter a name (for example `Perplexity laptop`). Optionally set an expiry.
+4. Tap **Create token**.
+5. Copy the MCP URL, the full `mcp_…` secret, or the JSON snippet from the modal. The secret is shown **once**. Close the modal only after you have stored it in the client.
+
+Cap is **10** active tokens per user. List rows show prefix (`mcp_` + eight hex characters), last used, and expiry — never the full secret.
+
+## 3. Mint a token (curl)
+
+Use a session or JWT. A service token cannot mint another token.
+
+```bash
+curl -X POST "$API/mcp/service-tokens" \
+  -H "Authorization: Bearer $JWT" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Perplexity"}'
+```
+
+Read `data.token` and `data.mcpUrl` from the JSON. List and revoke never return `token`. Do not log the secret.
+
+## 4. Perplexity custom connector
+
+| Field | Value |
+| --- | --- |
+| MCP Server URL | `https://api.example.com/mcp` (use `data.mcpUrl` from create) |
+| Transport | Streamable HTTP |
+| Authentication | API Key |
+| API Key | full `mcp_…` string (Perplexity sends as Bearer) |
+
+Perplexity probes with GET, then POSTs JSON-RPC. Send the same key on both.
+
+GET does **not** authenticate. This server has no GET SSE stream, so `/mcp` answers `405` with `{"jsonrpc":"2.0","error":{"code":-32000,"message":"Method not allowed."}}` whether or not the key is valid. That 405 is the expected probe — not a failed login.
+
+POST `initialize` and `tools/list` are the unauthenticated catalog in the stateless handler. Identity is checked when a **tool runs** (`tools/call`). A missing or invalid `mcp_` key then returns `Permission denied: authentication required`.
+
+## 5. Cursor, VS Code, Claude Code (JSON)
+
+```json
+{
+  "mcpServers": {
+    "my-app": {
+      "url": "https://api.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer mcp_<secret-shown-once>"
+      }
+    }
+  }
+}
+```
+
+Replace the URL with `data.mcpUrl` and the Bearer value with the one-time `data.token`.
+
+## 6. Prove the key with curl
+
+```bash
+# Expected probe: JSON-RPC 405 "Method not allowed."
+curl -X GET "$API/mcp" \
+  -H "Authorization: Bearer mcp_…" \
+  -H "Accept: application/json, text/event-stream"
+
+# Catalog is unauthenticated. Identity is not proven here.
+curl -X POST "$API/mcp" \
+  -H "Authorization: Bearer mcp_…" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"curl","version":"0"}}}'
+
+# Identity check: tools/call as the owning user. Use a tool name from tools/list.
+curl -X POST "$API/mcp" \
+  -H "Authorization: Bearer mcp_…" \
+  -H "Accept: application/json, text/event-stream" \
+  -H "Content-Type: application/json" \
+  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"todos_list","arguments":{}}}'
+```
+
+A bogus key such as `mcp_deadbeef` on `tools/call` is denied. A valid key sees the same owner-scoped result as that user's REST session.
+
+The token acts as the owning user on **MCP only**. It cannot mint or list tokens, and it is not valid on REST, sync, or admin routes.
+
+## 7. Revoke
+
+- **Owner:** Profile → MCP connections → **Revoke** on the row (`DELETE /mcp/service-tokens/:id`).
+- **Admin:** Admin → MCP service tokens (`/admin/mcp-service-tokens`). Create and update are off. Delete sets `revokedAt`; it does not hard-delete the row.
+
+Revoked and expired keys fail `tools/call` immediately. Disabled user accounts are refused the same way as over HTTP.

package/src/docs/versioned/57.15.0/how-to/create-a-model.md

@@ -0,0 +1,165 @@
+# How to Create a Mongoose Model
+
+Learn how to create a Mongoose model with Terreno conventions for use with modelRouter.
+
+## Prerequisites
+
+- Basic understanding of MongoDB and Mongoose
+- @terreno/api installed
+- MongoDB connection configured
+
+## Step-by-step
+
+### 1. Define TypeScript interfaces
+
+Create type definitions for your model document, model statics, and methods:
+
+``````typescript
+// src/types/models/todoTypes.ts
+import type mongoose from "mongoose";
+import type {DefaultDoc, DefaultModel} from "@terreno/api";
+
+export interface TodoDocument extends DefaultDoc {
+  title: string;
+  completed: boolean;
+  ownerId: mongoose.Types.ObjectId;
+}
+
+export interface TodoModel extends DefaultModel<TodoDocument> {
+  // Add custom static methods here if needed
+}
+``````
+
+### 2. Create the schema with field descriptions
+
+**Important:** Every field **must** include a `description` property. Terreno's `describeModel()` reads descriptions into the canonical field graph; that graph feeds the OpenAPI spec, admin `/admin/config` field metadata, and MCP tool schemas.
+
+``````typescript
+// src/models/todo.ts
+import mongoose from "mongoose";
+import type {TodoDocument, TodoModel} from "../types";
+import {addDefaultPlugins} from "./modelPlugins";
+
+const todoSchema = new mongoose.Schema<TodoDocument, TodoModel>(
+  {
+    completed: {
+      default: false,
+      description: "Whether the todo item has been completed",
+      type: Boolean,
+    },
+    ownerId: {
+      description: "The user who owns this todo",
+      ref: "User",
+      required: true,
+      type: mongoose.Schema.Types.ObjectId,
+    },
+    title: {
+      description: "The title of the todo item",
+      required: true,
+      trim: true,
+      type: String,
+    },
+  },
+  {
+    strict: "throw",
+    toJSON: {virtuals: true},
+    toObject: {virtuals: true},
+  }
+);
+``````
+
+### 3. Add plugins
+
+Apply default plugins to get standard fields (created, updated, deleted):
+
+``````typescript
+addDefaultPlugins(todoSchema);
+``````
+
+The default plugins typically include:
+- `createdUpdatedPlugin` — Adds `created` and `updated` timestamps
+- `isDeletedPlugin` — Adds soft delete support with `deleted` field
+- `findExactlyOne` and `findOneOrNone` — Safe query methods
+
+### 4. Export the model
+
+``````typescript
+export const Todo = mongoose.model<TodoDocument, TodoModel>("Todo", todoSchema);
+``````
+
+### 5. Create routes with modelRouter
+
+Use the model with `modelRouter` to generate CRUD endpoints:
+
+``````typescript
+// src/api/todos.ts
+import {Router} from "express";
+import {modelRouter, Permissions, OwnerQueryFilter} from "@terreno/api";
+import {Todo} from "../models/todo";
+
+export const addTodoRoutes = (router: Router) => {
+  router.use(
+    "/todos",
+    modelRouter(Todo, {
+      permissions: {
+        create: [Permissions.IsAuthenticated],
+        list: [Permissions.IsAuthenticated],
+        read: [Permissions.IsOwner],
+        update: [Permissions.IsOwner],
+        delete: [Permissions.IsOwner],
+      },
+      preCreate: (body, req) => ({
+        ...body,
+        ownerId: req.user?._id,
+      }),
+      queryFilter: OwnerQueryFilter,
+      queryFields: ["completed", "ownerId"],
+      sort: "-created",
+    })
+  );
+};
+``````
+
+## Field description guidelines
+
+When writing field descriptions:
+
+- **Be concise:** One clear sentence is usually enough
+- **Explain purpose, not type:** The type is already specified
+- **Use active voice:** "The user who owns..." not "The owner of..."
+- **Include constraints if relevant:** "Email address (must be unique)"
+
+### Good examples
+
+``````typescript
+{
+  email: {
+    description: "User's email address (must be unique)",
+    type: String,
+    required: true,
+    unique: true,
+  },
+  createdAt: {
+    description: "Timestamp when the record was created",
+    type: Date,
+    default: Date.now,
+  },
+  status: {
+    description: "Current status of the order",
+    type: String,
+    enum: ["pending", "processing", "completed"],
+  },
+}
+``````
+
+## Next steps
+
+- Learn about [modelRouter options](../reference/api.md)
+- Explore [permissions and access control](../reference/api.md#permissions)
+- See the [example-backend](../../example-backend/) for a complete working example
+
+## See also
+
+- [@terreno/api reference](../reference/api.md)
+- [Getting started tutorial](../tutorials/getting-started.md)
+- [example-backend source](../../example-backend/src/models/)