@softr/sdk 0.0.63 → 0.0.64-alpha.1

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 "./visibility/route.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.63";
+var version = "0.0.64-alpha.1";
 
 //#endregion
 export { version };

package/dist/softr-config.d.ts

@@ -0,0 +1 @@
+import { z } from "zod";

package/dist/softr-config.js

@@ -9,11 +9,32 @@ const AccessBehaviour = z.union([
 	}),
 	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
-}) }) });
+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

@@ -1,4 +1,5 @@
 import { AccessContext, AccessReason, Narrowed, Visibility, VisibilityRule } from "./visibility.js";
+import "../softr-config.js";
 
 //#region src/visibility/route.d.ts
 
@@ -46,7 +47,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 {@link toReturnPath} to read back.
  *
  * Throws a router redirect, so it belongs in `beforeLoad` and nowhere else.
  *
@@ -55,17 +57,43 @@ 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>;
+};
+/**
+ * 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))
+ */
+declare function toReturnPath(location: {
+  search: Record<string, unknown>;
+}): {
+  href: string;
+  reloadDocument: true;
+};
 //#endregion
-export { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError };
+export { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError, toReturnPath };

package/dist/visibility/route.js

@@ -32,14 +32,24 @@ 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) {
-	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 +59,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 {@link toReturnPath} to read back.
 *
 * Throws a router redirect, so it belongs in `beforeLoad` and nowhere else.
 *
@@ -57,10 +68,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,16 +79,47 @@ 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);
+}
+/**
+* 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
+	};
 }
 
 //#endregion
-export { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError };
+export { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError, softrConfig, toReturnPath };

package/package.json

@@ -1,16 +1,37 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.63",
+  "version": "0.0.64-alpha.1",
   "type": "module",
   "exports": {
-    ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },
-    "./client": { "types": "./dist/client.d.ts", "import": "./dist/client.js" },
-    "./server": { "types": "./dist/server.d.ts", "import": "./dist/server.js" },
-    "./vite": { "types": "./dist/vite.d.ts", "import": "./dist/vite.js" }
-  },
-  "bin": { "softr-sdk": "./dist/cli.js" },
-  "files": ["dist", "schema", "skills", "!skills/_artifacts"],
-  "publishConfig": { "access": "public" },
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "import": "./dist/client.js"
+    },
+    "./server": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    },
+    "./vite": {
+      "types": "./dist/vite.d.ts",
+      "import": "./dist/vite.js"
+    }
+  },
+  "bin": {
+    "softr-sdk": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "schema",
+    "skills",
+    "!skills/_artifacts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsdown",
     "test": "node --import ./src/test-utils/setup.ts --test",
@@ -42,7 +63,9 @@
       "optional": true
     }
   },
-  "keywords": ["tanstack-intent"],
+  "keywords": [
+    "tanstack-intent"
+  ],
   "intent": {
     "version": 1,
     "repo": "@softr/sdk",

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.61
+  library_version: 0.0.64-alpha.1
 ---
 
 # Softr SDK core