@softr/sdk 0.0.64-alpha.1 → 0.0.65-alpha.0

package/dist/visibility/route.js

@@ -32,24 +32,14 @@ function isForbiddenError(error) {
 function isAlreadyAuthenticatedError(error) {
 	return isReason(error, "alreadyAuthenticated");
 }
-function softrConfig() {
-	return typeof __SOFTR_CONFIG__ === "undefined" ? panic("softr.json is missing") : __SOFTR_CONFIG__;
-}
 /** What a guard throws for a reason: a redirect, or an {@link AccessError}. */
-function thrownFor(reason, overrides, location) {
-	const behaviour = overrides?.[reason] ?? softrConfig().auth.guard[reason];
+function thrownFor(reason, overrides) {
+	const behaviour = overrides?.[reason] ?? (typeof __SOFTR_CONFIG__ === "undefined" ? panic("softr.json is missing, so no guard behaviour is configured") : __SOFTR_CONFIG__.auth.guard[reason]);
 	const resolved = typeof behaviour === "string" ? {
 		strategy: "redirect",
 		to: behaviour
 	} : behaviour;
-	if (resolved.strategy === "redirect") {
-		if (reason !== "unauthenticated") return redirect({ to: resolved.to });
-		const { redirectParam } = softrConfig().auth.routes.login;
-		return redirect({
-			to: resolved.to,
-			search: { [redirectParam]: location.href }
-		});
-	}
+	if (resolved.strategy === "redirect") return redirect({ to: resolved.to });
 	return {
 		type: "access_error",
 		reason
@@ -59,8 +49,7 @@ function thrownFor(reason, overrides, location) {
 * A `beforeLoad` handler that denies a visitor who fails the rule.
 *
 * Each reason falls back to the app's configured behaviour. Pass `overrides` to
-* change what any one reason does. A redirected signed-out visitor carries the
-* page they wanted, for {@link toReturnPath} to read back.
+* change what any one reason does.
 *
 * Throws a router redirect, so it belongs in `beforeLoad` and nowhere else.
 *
@@ -68,10 +57,10 @@ function thrownFor(reason, overrides, location) {
 * beforeLoad: guardRoute(visibility, { unauthenticated: "/sign-in" })
 */
 function guardRoute(visibility, overrides) {
-	return ({ context, location }) => {
+	return ({ context }) => {
 		const result = checkAccess(visibility, context);
 		if (result.ok) return;
-		throw thrownFor(result.reason, overrides, location);
+		throw thrownFor(result.reason, overrides);
 	};
 }
 /**
@@ -79,47 +68,16 @@ function guardRoute(visibility, overrides) {
 * checks after the rule. It takes no overrides.
 *
 * @example
-* beforeLoad: (opts) => {
-*   assertRouteAccess(visibility, opts)
-*   if (opts.params.projectId === "demo") throw redirect({ to: "/projects" })
+* beforeLoad: ({ context, params }) => {
+*   assertRouteAccess(visibility, context)
+*   if (params.projectId === "demo") throw redirect({ to: "/projects" })
 * }
 */
-function assertRouteAccess(visibility, opts) {
-	const result = checkAccess(visibility, opts.context);
+function assertRouteAccess(visibility, context) {
+	const result = checkAccess(visibility, context);
 	if (result.ok) return;
-	throw thrownFor(result.reason, void 0, opts.location);
-}
-/**
-* Where to send a visitor who just signed in: the path a guard sent them away
-* from, else where `auth.guard.alreadyAuthenticated` in softr.json points, else
-* `/`. Anything but a path on this app counts as missing. It always reloads the
-* page, so the router picks up the new session.
-*
-* @example
-* const location = useLocation()
-* navigate(toReturnPath(location))
-*/
-function toReturnPath(location) {
-	const { auth } = softrConfig();
-	const target = location.search[auth.routes.login.redirectParam];
-	if (typeof target === "string" && target.startsWith("/") && new URL(target, "https://app.invalid").origin === "https://app.invalid") return {
-		href: target,
-		reloadDocument: true
-	};
-	const fallback = auth.guard.alreadyAuthenticated;
-	if (typeof fallback === "string") return {
-		href: fallback,
-		reloadDocument: true
-	};
-	if (fallback.strategy === "redirect") return {
-		href: fallback.to,
-		reloadDocument: true
-	};
-	return {
-		href: "/",
-		reloadDocument: true
-	};
+	throw thrownFor(result.reason, void 0);
 }
 
 //#endregion
-export { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError, softrConfig, toReturnPath };
+export { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.64-alpha.1",
+  "version": "0.0.65-alpha.0",
   "type": "module",
   "exports": {
     ".": {

package/schema/softr.schema.json

@@ -7,30 +7,6 @@
       "type": "object",
       "description": "Authentication. Written in this repo and read by the app's build.",
       "properties": {
-        "routes": {
-          "type": "object",
-          "description": "Where the app's sign-in pages live.",
-          "properties": {
-            "login": {
-              "type": "object",
-              "description": "The sign-in page.",
-              "properties": {
-                "path": { "$ref": "#/$defs/appPath" },
-                "redirectParam": {
-                  "type": "string",
-                  "description": "The search param that carries where to go after signing in. Every unauthenticated redirect sets it."
-                }
-              },
-              "required": ["path", "redirectParam"],
-              "additionalProperties": false
-            },
-            "resetPassword": { "$ref": "#/$defs/tokenRoute", "description": "The page a password reset email links to." },
-            "acceptInvitation": { "$ref": "#/$defs/tokenRoute", "description": "The page an invitation email links to." },
-            "magicLink": { "$ref": "#/$defs/tokenRoute", "description": "The page a magic link email links to." }
-          },
-          "required": ["login", "resetPassword", "acceptInvitation", "magicLink"],
-          "additionalProperties": false
-        },
         "guard": {
           "type": "object",
           "description": "What a route guard does when it denies a visitor. A route's own overrides win over these.",
@@ -52,29 +28,12 @@
           "additionalProperties": false
         }
       },
-      "required": ["routes", "guard"],
+      "required": ["guard"],
       "additionalProperties": false
     }
   },
   "required": ["auth"],
   "$defs": {
-    "appPath": {
-      "type": "string",
-      "pattern": "^/[^?#]*$",
-      "description": "A path on this app, with no search or hash."
-    },
-    "tokenRoute": {
-      "type": "object",
-      "properties": {
-        "path": { "$ref": "#/$defs/appPath" },
-        "tokenParam": {
-          "type": "string",
-          "description": "The search param that carries the link's token."
-        }
-      },
-      "required": ["path", "tokenParam"],
-      "additionalProperties": false
-    },
     "accessBehaviour": {
       "oneOf": [
         { "type": "string", "description": "A path to redirect to." },

package/skills/softr-sdk/SKILL.md

@@ -6,13 +6,12 @@ description: >-
   boundary between them, softrAuthMiddleware, getSoftrContext,
   initialSoftrContext, SoftrContext, and which sub-skill to load for route
   visibility, the current user, reading records, charts and metrics, writing
-  records, auth, or showing dates and numbers. Load this when unsure which
-  sub-skill applies, or when touching the wiring; each sub-skill stands alone
-  for its own task.
+  records, auth, or showing dates and numbers. Load this when unsure which sub-skill applies, or when
+  touching the wiring; each sub-skill stands alone for its own task.
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.64-alpha.1
+  library_version: 0.0.61
 ---
 
 # Softr SDK core

package/skills/softr-sdk/auth/SKILL.md

@@ -7,19 +7,16 @@ description: >-
   sign-in (verifyAuthenticator, startAuthenticatorSetup,
   confirmAuthenticatorSetup, skipAuthenticatorSetup) and the ones that change an
   authenticator from a settings page (sendAuthenticatorResetCode,
-  resetAuthenticator, removeAuthenticator), the emailed password links
-  (requestPasswordReset, checkPasswordLink, setPasswordWithLink), and
-  getAuthSettings, AuthSettingsProvider and useAuthSettings for which sign-in
-  and sign-up methods the app has enabled. Covers the Result shape they answer
-  with and its codes invalidCredentials, tooManyAttempts, emailTaken,
-  invalidDetails, invalidCode, notAuthenticated, emailDomainNotAllowed and
-  linkExpired, the two-step sign-up, why a successful sign-in does not always
-  mean the visitor is signed in, and toReturnPath for where to land after
-  signing in.
+  resetAuthenticator, removeAuthenticator). Covers the Result shape they answer
+  with ({ success, data } | { success, error }) and its codes
+  invalidCredentials, tooManyAttempts, emailTaken, invalidDetails, invalidCode
+  and notAuthenticated, the two-step sign-up, and why a successful sign-in does
+  not always mean the visitor is signed in. The blank template already ships
+  working login and signup pages.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64-alpha.1
+  library_version: 0.0.61
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build.
@@ -28,12 +25,6 @@ metadata:
 
 `auth` is what changes who the visitor is.
 
-Reading how the app signs people in:
-
-| Call | Does |
-| --- | --- |
-| `auth.settings()` | Returns the sign-in and sign-up settings the builder chose in Studio |
-
 Signing in:
 
 | Call | Does |
@@ -51,14 +42,6 @@ Signing up:
 | `auth.signUp({ email, name? })` | Emails a verification code, creates no account |
 | `auth.confirmSignUp({ email, code, name?, password? })` | Creates the account and signs the visitor in |
 
-Setting a password from an emailed link, for a password reset or an invitation:
-
-| Call | Does |
-| --- | --- |
-| `auth.requestPasswordReset({ email })` | Emails a link to set a new password |
-| `auth.checkPasswordLink({ token })` | Returns the `email` the link was sent to, and leaves the link usable |
-| `auth.setPasswordWithLink({ token, password })` | Sets the password and signs the visitor in |
-
 Signing out:
 
 | Call | Does |
@@ -82,6 +65,8 @@ Changing an authenticator from a settings page:
 | `auth.resetAuthenticator({ code })` | Unpairs the app, so a new one can be enrolled |
 | `auth.removeAuthenticator({ code })` | Turns the authenticator off |
 
+**The blank template already ships a working login page and signup page.** Read `src/routes/_auth/login.tsx` before writing anything new. Most tasks are an edit to those, not a new flow.
+
 ## Setup
 
 `auth` is server-only, so every call sits inside a `createServerFn` handler:
@@ -122,73 +107,29 @@ type AuthErrorCode =
   | 'invalidCredentials'   // signIn, signInWithGoogle, signInWithMagicLink: wrong password, or a token Softr would not take
   | 'tooManyAttempts'      // any call: rate limited
   | 'emailTaken'           // signUp, confirmSignUp: that email already has an account
-  | 'invalidDetails'       // signUp, sendSignInCode, setPasswordWithLink: details Softr rejected
+  | 'invalidDetails'       // signUp, sendSignInCode: details Softr rejected
   | 'invalidCode'          // any call that takes a code: wrong or expired
   | 'notAuthenticated'     // a call that needs a signed-in visitor, made by one who is not
-  | 'emailDomainNotAllowed' // signUp, signInWithGoogle: the app lets only some email domains sign up, and this is not one
-  | 'linkExpired'          // checkPasswordLink, setPasswordWithLink: the link is used, expired or no longer valid
 ```
 
 Branch on `error.code` with a `switch` and write your own wording. Never put `error.message` in front of the visitor.
 
 `code` is typed as every code the SDK produces, not the ones a given call can answer, so a `switch` needs a `default` even when the cases above it are complete. Give it a message rather than leaving it out.
 
-## Render only the methods the app has enabled
-
-`getAuthSettings` from `@softr/sdk` loads which ways in the app offers. Call it in the loader of a route that sits above every page needing it, and wrap that route's children in `AuthSettingsProvider`. If the auth pages share a layout route, that route is the usual place:
-
-```tsx
-import { AuthSettingsProvider, getAuthSettings } from '@softr/sdk'
-
-// in the route options
-loader: () => getAuthSettings(),
-staleTime: 60_000,
-
-// in the route's component
-const authSettings = Route.useLoaderData()
-return (
-  <AuthSettingsProvider value={authSettings}>
-    <Outlet />
-  </AuthSettingsProvider>
-)
-```
-
-Any page or component below it reads them with `useAuthSettings()`, which needs the provider above it:
-
-```tsx
-const options = useAuthSettings()
-return options.password && <PasswordForm />
-```
-
-Each field names the `auth` call it unlocks:
-
-| Field | When on, offer |
-| --- | --- |
-| `password` | the password form, `auth.signIn` |
-| `emailCode` | sign-in with a code, `auth.sendSignInCode` |
-| `magicLink` | the route that calls `auth.signInWithMagicLink` |
-| `google` | a Google button started with `google.clientId`. `null` means no Google. Never hardcode a client id. |
-| `signUp` | sign-up, `auth.signUp` |
-| `strongPasswords` | the strong-password rules, on every form that sets a new password. Check the password against them before submitting. |
-
-When the builder turns sign-in off, every field is off.
-
-Render nothing for a field that is off. A page for a flow that is off answers 404 from its loader. Throw `notFound()` there, never from the component: a component that renders nothing answers 200 with an empty page. `auth.settings()` returns the full settings, for a server function that needs more than these.
-
 ## A successful sign-in is not always a session
 
-`signIn`, `signInWithCode`, `signInWithGoogle`, `signInWithMagicLink`, `setPasswordWithLink` and `confirmSignUp` all answer the same two ways:
+`signIn`, `signInWithCode`, `signInWithGoogle`, `signInWithMagicLink` and `confirmSignUp` all answer the same two ways:
 
 ```ts
 { status: 'signedIn', user }
 { status: 'authenticatorRequired', step: 'verify' | 'setup' | 'setupOptional' }
 ```
 
-`signedIn` is a session. Send the visitor to the return target, see [Landing after sign-in](#landing-after-sign-in).
+`signedIn` is a session. Redirect into the app.
 
 `authenticatorRequired` is not. The app asks for an authenticator app as well, and the visitor has no session until they produce one. Redirecting into the app here sends them to a page they cannot see, and a guarded page bounces them back to the login form with nothing on screen explaining why.
 
-Show the second factor as the next step of the page that signed them in, not on a page of its own. Pick what it shows by `step`:
+Send them on by `step`:
 
 | `step` | Show them | Finish with |
 | --- | --- | --- |
@@ -200,27 +141,6 @@ Those calls take only what the visitor typed. The sign-in they finish is the one
 
 An app with no authenticator app configured never answers `authenticatorRequired`. The type still has both arms either way, so `result.data.user` does not exist until you have narrowed on `status`.
 
-## Landing after sign-in
-
-A guard that turns a signed-out visitor away sends them to the page `softr.json` names for that, usually the login page. The page they wanted rides along in the search param named for the login page. `toReturnPath` from `@softr/sdk` reads it back:
-
-```tsx
-import { useLocation, useNavigate } from '@tanstack/react-router'
-import { toReturnPath } from '@softr/sdk'
-
-const location = useLocation()
-const navigate = useNavigate()
-
-// once the visitor is signed in
-await navigate(toReturnPath(location))
-```
-
-A loader that signs the visitor in throws it instead: `throw redirect(toReturnPath(location))`, with the loader's own `location`.
-
-It goes to the page they wanted when that is a path on this app. Otherwise it goes where `auth.guard.alreadyAuthenticated` in `softr.json` points, or to `/` when that setting throws. It reloads the page, so the app sees the visitor as signed in. Pass its answer as is. Never read the param yourself: anyone can put a link to another site in it.
-
-Every page that ends a sign-in lands there: login, sign-up, the magic link, a password link and the second-factor step. A link from one auth page to another keeps the search param, or the target is lost on the way.
-
 ## Core Patterns
 
 ### Sign in
@@ -242,27 +162,24 @@ const signIn = createServerFn({ method: 'POST' })
       }
     }
 
-    return { message: null, outcome: result.data }
+    if (result.data.status === 'authenticatorRequired') {
+      throw redirect({ to: '/verify', search: { step: result.data.step } })
+    }
+
+    throw redirect({ to: '/' })
   })
 ```
 
-The component takes it from there:
+Three exits: a message for the form to render, a redirect to the second factor, a redirect into the app.
+
+Call it from the component with `useServerFn`:
 
 ```tsx
 import { useServerFn } from '@tanstack/react-start'
 
 const submit = useServerFn(signIn)
-
-const answer = await submit({ data: { email, password } })
-if (answer.message !== null) return setMessage(answer.message)
-if (answer.outcome.status === 'authenticatorRequired') {
-  return setStep({ name: 'secondFactor', opensOn: answer.outcome.step })
-}
-await navigate({ href: target })
 ```
 
-Three exits: a message for the form to render, the second-factor step, the return target.
-
 A server function that throws `redirect` needs the hook. Call the imported function directly and the throw never reaches the router, so a successful sign-in leaves the visitor on the form.
 
 A login page is a `NON_LOGGED_IN_USERS` route, which is what keeps an already-signed-in visitor off it. See [routes-and-visibility](../routes-and-visibility/SKILL.md).
@@ -304,25 +221,6 @@ const result = await auth.signInWithMagicLink({ token })
 
 The token keeps working after it is used, so anyone holding the link can sign in as that visitor. Never log it, and redirect away from the URL that carried it.
 
-### Set a password from an emailed link
-
-A password reset and an invitation both email a link with a token. The same two calls redeem either.
-
-```ts
-// The forgot-password form. Succeeds whether or not the address has an account.
-const sent = await auth.requestPasswordReset({ email })
-
-// The loader of the page the link opens. Show an expired message on linkExpired, before any form.
-const link = await auth.checkPasswordLink({ token })
-
-// The form's submit. Same two-armed result as signIn.
-const result = await auth.setPasswordWithLink({ token, password })
-```
-
-Say "check your email" after `requestPasswordReset` either way, and never branch the UI on it.
-
-`setPasswordWithLink` uses up the link on any success, `authenticatorRequired` included, and signs the visitor out everywhere else.
-
 ### Sign out
 
 ```ts
@@ -351,8 +249,6 @@ const startSignUp = createServerFn({ method: 'POST' })
           return { message: 'That email already has an account.' }
         case 'invalidDetails':
           return { message: 'Please check the details and try again.' }
-        case 'emailDomainNotAllowed':
-          return { message: 'Sign-up is open only to some email domains, and yours is not one.' }
         case 'tooManyAttempts':
           return { message: 'Too many attempts. Please try again in a few minutes.' }
         default:
@@ -380,7 +276,11 @@ const finishSignUp = createServerFn({ method: 'POST' })
       }
     }
 
-    return { message: null, outcome: result.data }   // handled as sign-in's is
+    if (result.data.status === 'authenticatorRequired') {
+      throw redirect({ to: '/verify', search: { step: result.data.step } })
+    }
+
+    throw redirect({ to: '/' })
   })
 ```
 
@@ -407,7 +307,7 @@ const verify = createServerFn({ method: 'POST' })
           return { message: 'Could not check that code. Please try again.' }
       }
     }
-    return { message: null }   // signed in: the component goes to the target
+    throw redirect({ to: '/' })
   })
 ```
 
@@ -429,12 +329,11 @@ Neither of those enrols anybody. `confirmAuthenticatorSetup` does, once it accep
 ```ts
 const done = await auth.confirmAuthenticatorSetup({ code })
 if (done.success) {
-  return { backupCodes: done.data.backupCodes }  // returned once. Render them now, nothing fetches them again.
+  done.data.backupCodes  // returned once. Render them now, nothing fetches them again.
+  throw redirect({ to: '/' })
 }
 ```
 
-The visitor is signed in while the codes are on screen, often on a page only signed-out visitors may see. Invalidating the router or navigating re-runs that page's guard, which sends them away and the codes are gone. Do neither until they click "Continue", then go to the target.
-
 Call `startAuthenticatorSetup` again to hand back a fresh QR code, for a visitor who lost the first one. Only the newest one enrols them.
 
 `skipAuthenticatorSetup` finishes the sign-in without enrolling, and only on `setupOptional`. Later sign-ins stop asking.
@@ -454,4 +353,5 @@ After a reset, enrol the new app with `startAuthenticatorSetup` and `confirmAuth
 ## References
 
 - [current-user/SKILL.md](../current-user/SKILL.md): reading the visitor these calls establish
-- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `NON_LOGGED_IN_USERS` and the `alreadyAuthenticated` redirect that keeps a signed-in visitor off a login page
+- [routes-and-visibility/SKILL.md](../routes-and-visibility/SKILL.md): `NON_LOGGED_IN_USERS` and the `alreadyAuthenticated` redirect that keeps a signed-in visitor off a login page
+- `src/routes/_auth/login.tsx` and `signup.tsx` in your own app: the implementations it was scaffolded with

package/skills/softr-sdk/charts-and-metrics/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64-alpha.1
+  library_version: 0.0.61
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/current-user/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64-alpha.1
+  library_version: 0.0.61
 ---
 
 # The current user

package/skills/softr-sdk/file-uploads/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64-alpha.1
+  library_version: 0.0.61
 ---
 
 **Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk` and run in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/formatting/SKILL.md

@@ -4,13 +4,13 @@ description: >-
   Show dates, times and numbers in the app's format without hydration
   mismatches: FormattedDate in JSX, useFormatting with formatDate,
   formatDateTime and formatNumber in code, FormattingScope and the timeZone
-  option for a zone or locale the user names, parts for a partial date, and why
-  toLocaleDateString, toLocaleString and Intl formatters with the runtime's
-  defaults must never run in render.
+  option for a zone or locale the user names, parts for a partial date, and
+  why toLocaleDateString, toLocaleString and Intl formatters with the
+  runtime's defaults must never run in render.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64-alpha.1
+  library_version: 0.0.61
 ---
 
 # Dates, times and numbers

package/skills/softr-sdk/integrations/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64-alpha.1
+  library_version: 0.0.61
 ---
 
 **Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineIntegration` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/mcp/SKILL.md

@@ -5,11 +5,11 @@ description: >-
   @softr/sdk, registered in src/start.ts ahead of softrAuthMiddleware, turns the
   actions you list into tools an assistant can call as the signed-in visitor.
   The list is explicit — an action left out is invisible over MCP. The app's own
-  login must land on toReturnPath, or the approval step dead-ends.
+  login must honour a `redirect` search param, or the approval step dead-ends.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64-alpha.1
+  library_version: 0.0.61
 ---
 
 **Boundary.** `softrMcpMiddleware` lives on `@softr/sdk` and is registered once, in `src/start.ts`. The actions you hand it are the same `defineQuery` / `defineMutation` values the app's own pages use — declared wherever they already live, not duplicated for MCP.
@@ -59,11 +59,18 @@ Reads first. Add a write only when the user asked for one, and name it back to t
 
 ## The login round trip
 
-Connecting starts with an approval page the app serves. Most people hit it signed out, and that page cannot sign anyone in. It sends them to the login page named in `softr.json` (`auth.routes.login.path`), with the approval page in the search param named there (`auth.routes.login.redirectParam`).
+Connecting starts with an approval page the app serves. Most people hit it signed out, and that page cannot sign anyone in. It sends them to the app's sign-in page with a `redirect` search param holding where to come back to. That page is `/login` unless you pass `loginPath`:
 
-**The app's login has to send them back.** Every exit that ends a sign-in, the second-factor step included, goes to `toReturnPath(location)` instead of the home page. See [auth/SKILL.md](../auth/SKILL.md). Lose the search param anywhere along the way and the approval dies quietly: they land on the home page, the assistant never gets its answer, nothing reports an error.
+```ts
+softrMcpMiddleware({ actions: [listCafes], loginPath: '/sign-in' })
+```
+
+**The app's login has to honour that param.** Carry it through every exit that ends a sign-in, the second-factor step included, and send the visitor there instead of the home page. Drop it anywhere along the way and the approval dies quietly: they land on the home page, the assistant never gets its answer, nothing reports an error.
+
+Validate it before following it. A path on this app and nothing else. Ask the URL parser rather than checking prefixes: resolve the value against a placeholder origin and reject it unless the origin survives. Browsers read `\` as `/` and drop tabs and newlines, so a value that does not start with `//` can still leave the app. The whole flow starts with a link someone was sent, so this is the one redirect an attacker can reliably aim.
+
+The blank template does this in `src/routes/_auth/login.tsx`, `src/routes/verify.tsx` and `src/lib/after-auth.ts`. Read those before writing your own.
 
-`toReturnPath` only ever goes to a path on this app. Never follow the param without it. The whole flow starts with a link someone was sent, so this is the one redirect an attacker can reliably aim.
 ## Failure modes
 
 **Registering with no actions.** `softrMcpMiddleware()` is valid and serves an endpoint with nothing on it. The assistant connects, lists tools, finds only `whoami`. Pass the actions.
@@ -72,9 +79,9 @@ Connecting starts with an approval page the app serves. Most people hit it signe
 
 **Handing over the app's URL as the MCP URL.** The origin is where the app's pages are. Without `/_softr/mcp` on the end the assistant has nothing to talk to, and the owner is left comparing a URL that looks right against a connection that never works.
 
-**A login that drops the return target.** Sign-in works, approval doesn't. The most common break, and silent — test the connect flow signed out, not only signed in.
+**A login that drops `redirect`.** Sign-in works, approval doesn't. The most common break, and silent — test the connect flow signed out, not only signed in.
 
-**Following the param without `toReturnPath`.** Anything that is not a path on this app is someone else's page, and `/\evil.test` is one of them. A prefix check misses it.
+**Following `redirect` unchecked, or checked by prefix.** Anything that is not a path on this app is someone else's page, and `/\evil.test` is one of them. Let the URL parser decide, and fall back to `/`.
 
 ## References
 

package/skills/softr-sdk/pwa/SKILL.md

@@ -4,12 +4,12 @@ description: >-
   Let visitors install the app on their home screen: SoftrPwaHead for the
   manifest and icon links, usePwaInstall to decide whether to show an install
   button and which platform's steps to show, the PwaInstall and PwaPlatform
-  types, and how to check that the app is installable. The manifest and icon are
-  already served; never write them.
+  types, and how to check that the app is installable. The manifest and icon
+  are already served; never write them.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64-alpha.1
+  library_version: 0.0.61
 ---
 
 # Installing the app

package/skills/softr-sdk/record-mutations/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64-alpha.1
+  library_version: 0.0.61
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineMutation` and every type come from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/record-queries/SKILL.md

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64-alpha.1
+  library_version: 0.0.61
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. The same holds for any helper that calls `ds`: declare it inside the handler. A function at module level that calls `ds` keeps the server-only import in the browser bundle, and every page stops loading until it moves. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere.
@@ -56,7 +56,8 @@ const publishedPosts = defineQuery({
 - `permissions` declares who may run the query, and the SDK enforces it:
   - `{ userGroupTypes: ['NON_LOGGED_IN_USERS', 'LOGGED_IN_USERS'] }`: everyone, signed out included. `customGroups` narrows only the signed-in half.
   - `{ userGroupTypes: ['NON_LOGGED_IN_USERS'] }`: signed-out visitors only.
-  - `{ userGroupTypes: ['LOGGED_IN_USERS'] }`: any signed-in visitor, narrowed to particular groups with `customGroups: ['00000000-0000-0000-0000-00000000000a']`.
+  - `{ userGroupTypes: ['LOGGED_IN_USERS'] }`: any signed-in visitor, narrowed to particular groups with `customGroups: ['00000000-0000-0000-0000-00000000000a']`. `customGroups` is added to `userGroupTypes`, never written in place of it.
+- Write each group id as a literal in `permissions`. An id taken from a `const` is a lint error, as it is in a route's visibility.
 - Write the object inline in the `defineQuery` call. Passing the declaration or its `fields` through a variable, or spreading one in, widens the field ids to `string` and the types stop checking.
 
 A query fixes the table and the columns, not the rows: filters, sorting and paging stay at the call site, because a list screen changes them as the user types. Declare as many queries over one datasource as the app needs, each carrying the fields its own screen touches.

package/skills/softr-sdk/region-visibility/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.64-alpha.1
+  library_version: 0.0.61
 ---
 
 **Boundary.** `Audience` and `defineVisibility` come from `@softr/sdk` and work anywhere.