@softr/sdk 0.0.64 → 0.0.65

package/dist/mcp.d.ts

@@ -1,5 +1,5 @@
 import { DatasourceAction } from "./action.js";
-import * as _tanstack_react_start3 from "@tanstack/react-start";
+import * as _tanstack_react_start4 from "@tanstack/react-start";
 
 //#region src/mcp.d.ts
 
@@ -12,12 +12,6 @@ type SoftrMcpOptions = {
    * decide who may run the ones that are listed.
    */
   actions?: Array<DatasourceAction>;
-  /**
-   * The app's sign-in page, as a path on this app. A signed-out visitor who
-   * opens the approval page is sent here with `?redirect=` pointing back at it.
-   * Defaults to `/login`.
-   */
-  loginPath?: string;
 };
 /**
  * Serves the MCP endpoint and its OAuth flow from the app's own origin.
@@ -37,6 +31,6 @@ type SoftrMcpOptions = {
  *   ],
  * }))
  */
-declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start3.RequestMiddlewareAfterServer<{}, undefined, undefined>;
+declare function softrMcpMiddleware(options?: SoftrMcpOptions): _tanstack_react_start4.RequestMiddlewareAfterServer<{}, undefined, undefined>;
 //#endregion
 export { softrMcpMiddleware };

package/dist/mcp.js

@@ -4,6 +4,7 @@ import { sessionConfig } from "./auth/config.js";
 import { readSessionToken, withSessionToken } from "./auth/session.js";
 import { makePlatform, platformApiUrl } from "./auth/platform.js";
 import { isDatasourceAction } from "./action.js";
+import { softrConfig } from "./softr-config.js";
 import { ds } from "./datasource/datasource.js";
 import { createMiddleware } from "@tanstack/react-start";
 import { z } from "zod";
@@ -38,8 +39,7 @@ const SUPPORTED_PROTOCOL_VERSIONS = ["2025-06-18", "2025-03-26"];
 * }))
 */
 function softrMcpMiddleware(options = {}) {
-	const loginPath = options.loginPath ?? "/login";
-	assert(loginPath.startsWith("/") && new URL(loginPath, "https://app.invalid").origin === "https://app.invalid", `softrMcpMiddleware's loginPath must be a path on this app, got "${loginPath}"`);
+	const login = softrConfig().auth.routes.login;
 	const actions = /* @__PURE__ */ new Map();
 	for (const action of options.actions ?? []) {
 		assert(isDatasourceAction(action), "softrMcpMiddleware takes actions built by defineQuery or defineMutation");
@@ -68,7 +68,7 @@ function softrMcpMiddleware(options = {}) {
 				client_id_metadata_document_supported: true,
 				scopes_supported: SCOPES
 			});
-			case AUTHORIZE_PATH: return await authorize(request, loginPath);
+			case AUTHORIZE_PATH: return await authorize(request, login);
 			case TOKEN_PATH: return await issueToken(request);
 			case MCP_PATH: return await rpc(request, origin, actions);
 			default: return await next();
@@ -92,14 +92,14 @@ const authorizeQuerySchema = z.object({
 * because this runs on the app's origin. The client and the code are the
 * platform's, so we ask it for both.
 */
-async function authorize(request, loginPath) {
+async function authorize(request, login) {
 	const url = new URL(request.url);
 	const query = authorizeQuerySchema.safeParse(Object.fromEntries(url.searchParams));
 	if (!query.success) return html(400, page("This request is not valid", "The app that sent you here left something out. Close this window and try connecting again."));
 	if (request.method !== "GET" && request.method !== "POST") return methodNotAllowed("GET, POST");
 	const sessionToken = readSessionToken();
 	const user = sessionToken === null ? null : await resolveUser(sessionToken);
-	if (user === null || sessionToken === null) return html(200, signInPage(url, loginPath));
+	if (user === null || sessionToken === null) return html(200, signInPage(url, login));
 	const client = await platformConsent(query.data);
 	if (!client.ok) return html(400, page("We can't connect this right now", escapeHtml(client.message)));
 	if (request.method === "GET") return html(200, consentPage(user, url, client.name));
@@ -539,9 +539,9 @@ function consentPage(user, url, clientName) {
        <button type="submit" name="decision" value="deny">Cancel</button>
      </form>`);
 }
-function signInPage(url, loginPath) {
-	const back = encodeURIComponent(url.pathname + url.search);
-	return page("Sign in first", "You need to be signed in to this app before you can connect an assistant to it.", `<a class="primary" href="${escapeHtml(loginPath)}?redirect=${back}">Sign in</a>`);
+function signInPage(url, login) {
+	const back = new URLSearchParams({ [login.redirectParam]: url.pathname + url.search });
+	return page("Sign in first", "You need to be signed in to this app before you can connect an assistant to it.", `<a class="primary" href="${escapeHtml(`${login.path}?${back}`)}">Sign in</a>`);
 }
 function page(title, body, actions = "") {
 	return `<!doctype html>

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.64";
+var version = "0.0.65";
 
 //#endregion
 export { version };

package/dist/pwa.d.ts

@@ -1,4 +1,4 @@
-import * as react3 from "react";
+import * as react4 from "react";
 import "@tanstack/react-start";
 
 //#region src/pwa.d.ts
@@ -23,7 +23,7 @@ import "@tanstack/react-start";
  *   )
  * }
  */
-declare function SoftrPwaHead(): react3.FunctionComponentElement<react3.FragmentProps>;
+declare function SoftrPwaHead(): react4.FunctionComponentElement<react4.FragmentProps>;
 type PwaPlatform = "ios" | "android" | "desktop";
 type PwaInstall = {
   available: false;

package/dist/softr-config.js

@@ -1,19 +1,9 @@
-import { z } from "zod";
+import { panic } from "./assertions.js";
 
 //#region src/softr-config.ts
-const AccessBehaviour = z.union([
-	z.string(),
-	z.object({
-		strategy: z.literal("redirect"),
-		to: z.string()
-	}),
-	z.object({ strategy: z.literal("throw") })
-], { error: "must be a path like \"/login\", { \"strategy\": \"redirect\", \"to\": \"/login\" } or { \"strategy\": \"throw\" }" });
-const SoftrConfigSchema = z.object({ auth: z.strictObject({ guard: z.strictObject({
-	unauthenticated: AccessBehaviour,
-	forbidden: AccessBehaviour,
-	alreadyAuthenticated: AccessBehaviour
-}) }) });
+function softrConfig() {
+	return typeof __SOFTR_CONFIG__ === "undefined" ? panic("softr.json is missing") : __SOFTR_CONFIG__;
+}
 
 //#endregion
-export { SoftrConfigSchema };
+export { softrConfig };

package/dist/softr-config.schema.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+
+//#region src/softr-config.schema.ts
+const AccessBehaviour = z.union([
+	z.string(),
+	z.object({
+		strategy: z.literal("redirect"),
+		to: z.string()
+	}),
+	z.object({ strategy: z.literal("throw") })
+], { error: "must be a path like \"/login\", { \"strategy\": \"redirect\", \"to\": \"/login\" } or { \"strategy\": \"throw\" }" });
+const AppPath = z.string().refine((path) => path.startsWith("/") && !path.includes("?") && !path.includes("#") && new URL(path, "https://app.invalid").origin === "https://app.invalid", { error: "must be a path on this app like \"/login\", with no \"?\" or \"#\"" });
+const SoftrConfigSchema = z.object({ auth: z.strictObject({
+	routes: z.strictObject({
+		login: z.strictObject({
+			path: AppPath,
+			redirectParam: z.string()
+		}),
+		resetPassword: z.strictObject({
+			path: AppPath,
+			tokenParam: z.string()
+		}),
+		acceptInvitation: z.strictObject({
+			path: AppPath,
+			tokenParam: z.string()
+		}),
+		magicLink: z.strictObject({
+			path: AppPath,
+			tokenParam: z.string()
+		})
+	}),
+	guard: z.strictObject({
+		unauthenticated: AccessBehaviour,
+		forbidden: AccessBehaviour,
+		alreadyAuthenticated: AccessBehaviour
+	})
+}) });
+
+//#endregion
+export { SoftrConfigSchema };

package/dist/visibility/route.d.ts

@@ -46,7 +46,8 @@ declare function isAlreadyAuthenticatedError(error: unknown): error is AccessErr
  * 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.
+ * change what any one reason does. A redirected signed-out visitor carries the
+ * page they wanted, for `toReturnPath` to read back.
  *
  * Throws a router redirect, so it belongs in `beforeLoad` and nowhere else.
  *
@@ -55,17 +56,27 @@ declare function isAlreadyAuthenticatedError(error: unknown): error is AccessErr
  */
 declare function guardRoute(visibility: Visibility, overrides?: GuardOverrides): (opts: {
   context: AccessContext;
+  location: {
+    href: string;
+  };
 }) => void;
 /**
  * Throws what {@link guardRoute} would, for a `beforeLoad` that runs its own
  * checks after the rule. It takes no overrides.
  *
  * @example
- * beforeLoad: ({ context, params }) => {
- *   assertRouteAccess(visibility, context)
- *   if (params.projectId === "demo") throw redirect({ to: "/projects" })
+ * beforeLoad: (opts) => {
+ *   assertRouteAccess(visibility, opts)
+ *   if (opts.params.projectId === "demo") throw redirect({ to: "/projects" })
  * }
  */
-declare function assertRouteAccess<R extends VisibilityRule>(visibility: Visibility<R>, context: AccessContext): asserts context is Narrowed<R>;
+declare function assertRouteAccess<R extends VisibilityRule, O extends {
+  context: AccessContext;
+  location: {
+    href: string;
+  };
+}>(visibility: Visibility<R>, opts: O): asserts opts is O & {
+  context: Narrowed<R>;
+};
 //#endregion
 export { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError };

package/dist/visibility/route.js

@@ -1,5 +1,5 @@
-import { panic } from "../assertions.js";
 import { ACCESS_REASONS, checkAccess } from "./visibility.js";
+import { softrConfig } from "../softr-config.js";
 import { redirect } from "@tanstack/react-router";
 
 //#region src/visibility/route.ts
@@ -33,13 +33,20 @@ function isAlreadyAuthenticatedError(error) {
 	return isReason(error, "alreadyAuthenticated");
 }
 /** What a guard throws for a reason: a redirect, or an {@link AccessError}. */
-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]);
+function thrownFor(reason, overrides, location) {
+	const behaviour = overrides?.[reason] ?? softrConfig().auth.guard[reason];
 	const resolved = typeof behaviour === "string" ? {
 		strategy: "redirect",
 		to: behaviour
 	} : behaviour;
-	if (resolved.strategy === "redirect") return redirect({ to: resolved.to });
+	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 }
+		});
+	}
 	return {
 		type: "access_error",
 		reason
@@ -49,7 +56,8 @@ function thrownFor(reason, overrides) {
 * 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.
+* change what any one reason does. A redirected signed-out visitor carries the
+* page they wanted, for `toReturnPath` to read back.
 *
 * Throws a router redirect, so it belongs in `beforeLoad` and nowhere else.
 *
@@ -57,10 +65,10 @@ function thrownFor(reason, overrides) {
 * beforeLoad: guardRoute(visibility, { unauthenticated: "/sign-in" })
 */
 function guardRoute(visibility, overrides) {
-	return ({ context }) => {
+	return ({ context, location }) => {
 		const result = checkAccess(visibility, context);
 		if (result.ok) return;
-		throw thrownFor(result.reason, overrides);
+		throw thrownFor(result.reason, overrides, location);
 	};
 }
 /**
@@ -68,15 +76,15 @@ function guardRoute(visibility, overrides) {
 * checks after the rule. It takes no overrides.
 *
 * @example
-* beforeLoad: ({ context, params }) => {
-*   assertRouteAccess(visibility, context)
-*   if (params.projectId === "demo") throw redirect({ to: "/projects" })
+* beforeLoad: (opts) => {
+*   assertRouteAccess(visibility, opts)
+*   if (opts.params.projectId === "demo") throw redirect({ to: "/projects" })
 * }
 */
-function assertRouteAccess(visibility, context) {
-	const result = checkAccess(visibility, context);
+function assertRouteAccess(visibility, opts) {
+	const result = checkAccess(visibility, opts.context);
 	if (result.ok) return;
-	throw thrownFor(result.reason, void 0);
+	throw thrownFor(result.reason, void 0, opts.location);
 }
 
 //#endregion

package/dist/vite.js

@@ -1,5 +1,5 @@
 import { assert, panic } from "./assertions.js";
-import { SoftrConfigSchema } from "./softr-config.js";
+import { SoftrConfigSchema } from "./softr-config.schema.js";
 import { existsSync, readFileSync } from "node:fs";
 import path from "node:path";
 import { z } from "zod";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.64",
+  "version": "0.0.65",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },

package/schema/softr.schema.json

@@ -7,6 +7,30 @@
       "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.",
@@ -28,12 +52,29 @@
           "additionalProperties": false
         }
       },
-      "required": ["guard"],
+      "required": ["routes", "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,12 +6,13 @@ 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
+  library_version: 0.0.65
 ---
 
 # Softr SDK core