@softr/sdk 0.0.45-alpha.0 → 0.0.45

package/dist/auth/context.d.ts

@@ -6,7 +6,7 @@ import { Permissions } from "./permissions.js";
 type Session = {
   /** The visitor, or `null` when signed out. */
   user: User | null;
-  /** What the visitor may do, signed in or not. */
+  /** The visitor's global data restrictions. An escape hatch; the SDK already checks them. */
   permissions: Permissions;
 };
 /**

package/dist/auth/isomorphic.d.ts

@@ -1,5 +1,5 @@
 import { User } from "./user.js";
-import { DatasourcePermissions, Permissions } from "./permissions.js";
+import { Permissions } from "./permissions.js";
 import { Session, SoftrContext } from "./context.js";
 import * as _tanstack_react_start0 from "@tanstack/react-start";
 
@@ -51,22 +51,5 @@ declare function initialSoftrContext(): SoftrContext;
  * }
  */
 declare function useCurrentUser(): User | null;
-/**
- * Resolves what the current user may do with one datasource.
- *
- * A rendering hint: every request is authorized again on the server, so never
- * let this stand in for a permission check.
- *
- * Requires the root route to resolve {@link getSoftrContext}.
- *
- * @example
- * function NewRecordButton() {
- *   const { create } = usePermissions(datasourceId)
- *   return create ? <button>New record</button> : null
- * }
- *
- * @throws if the application has no such datasource.
- */
-declare function usePermissions(datasourceId: string): DatasourcePermissions;
 //#endregion
-export { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions };
+export { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser };

package/dist/auth/isomorphic.js

@@ -1,4 +1,4 @@
-import { assert, panic, requireDefined } from "../assertions.js";
+import { assert, panic } from "../assertions.js";
 import { writeCookies } from "../cookies.js";
 import { sessionConfig } from "./config.js";
 import { clearSession, makeSessionDataCookie, readSessionData, readSessionToken } from "./session.js";
@@ -87,28 +87,6 @@ function useCurrentUser() {
 		select: (context) => context.user
 	});
 }
-/**
-* Resolves what the current user may do with one datasource.
-*
-* A rendering hint: every request is authorized again on the server, so never
-* let this stand in for a permission check.
-*
-* Requires the root route to resolve {@link getSoftrContext}.
-*
-* @example
-* function NewRecordButton() {
-*   const { create } = usePermissions(datasourceId)
-*   return create ? <button>New record</button> : null
-* }
-*
-* @throws if the application has no such datasource.
-*/
-function usePermissions(datasourceId) {
-	return useRouteContext({
-		from: rootRouteId,
-		select: (context) => requireDefined(context.permissions.datasources[datasourceId], `the application has no datasource "${datasourceId}"`)
-	});
-}
 
 //#endregion
-export { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions };
+export { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser };

package/dist/auth/permissions.d.ts

@@ -19,4 +19,4 @@ type Permissions = {
   datasources: Record<string, DatasourcePermissions>;
 };
 //#endregion
-export { DatasourcePermissions, Permissions };
+export { Permissions };

package/dist/auth/session.js

@@ -3,7 +3,6 @@ import { permissionsSchema } from "./permissions.js";
 import { sessionConfig } from "./config.js";
 import { userSchema } from "./user.js";
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from "node:crypto";
-import { AsyncLocalStorage } from "node:async_hooks";
 import { getRequestProtocol } from "@tanstack/react-start/server";
 import { z } from "zod";
 
@@ -36,20 +35,8 @@ function sessionCookie(base) {
 		secure
 	};
 }
-/**
-* Runs `fn` with `token` standing in for the request's session cookie, so that
-* every datasource call inside it acts as that visitor.
-*
-* For requests that carry who they are somewhere other than the cookie: an MCP
-* call authenticates with a bearer token and has no cookie at all.
-*/
-function withSessionToken(token, fn) {
-	return standInToken.run(token, fn);
-}
 /** The platform token this request carries, or `null`. */
 function readSessionToken() {
-	const standIn = standInToken.getStore();
-	if (standIn !== void 0) return standIn;
 	const { name } = sessionCookie(SESSION_TOKEN);
 	return openEnvelope(readRequestCookies()[name], SESSION_TOKEN);
 }
@@ -118,7 +105,6 @@ function clearSession() {
 		PENDING_AUTH
 	]);
 }
-const standInToken = new AsyncLocalStorage();
 const sessionDataSchema = z.object({
 	user: userSchema.nullable(),
 	permissions: permissionsSchema,
@@ -210,4 +196,4 @@ function openEnvelope(raw, purpose) {
 }
 
 //#endregion
-export { clearPendingAuth, clearSession, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie, readPendingAuthToken, readSessionData, readSessionToken, withSessionToken };
+export { clearPendingAuth, clearSession, makePendingAuthCookie, makeSessionDataCookie, makeSessionTokenCookie, readPendingAuthToken, readSessionData, readSessionToken };

package/dist/datasource/chart.js

@@ -4,7 +4,7 @@ import { readUserTimezone } from "../cookies.js";
 import { readSessionToken } from "../auth/session.js";
 import { INTERNAL_KIND, buildFilterCriteria, buildOrderBy, dealiasFilterCriteria } from "./filter.js";
 import { andAll, makeFieldSet, makeSortSet } from "./fields.js";
-import { dsUrl, resolveTarget } from "./record.js";
+import { describeFailure, dsUrl, resolveTarget } from "./record.js";
 
 //#region src/datasource/chart.ts
 const COUNT_CNT = "COUNT_CNT";
@@ -202,7 +202,7 @@ async function executeChart(query, state) {
 		},
 		body: JSON.stringify(body)
 	});
-	if (!res.ok) throw new Error(`Softr datasource chart failed for action "${actionId}": ${res.status}`);
+	if (!res.ok) throw new Error(`datasource chart failed for action "${actionId}": ${await describeFailure(res)}`);
 	const payload = await res.json();
 	return {
 		data: mapChartRows(columns, payload.data),
@@ -275,7 +275,7 @@ async function executeMetric(query, handle, filters) {
 		},
 		body: JSON.stringify(body)
 	});
-	if (!res.ok) throw new Error(`Softr datasource metric failed for action "${actionId}": ${res.status}`);
+	if (!res.ok) throw new Error(`datasource metric failed for action "${actionId}": ${await describeFailure(res)}`);
 	const payload = await res.json();
 	return {
 		value: readMetricValue(responseKey, payload.data),

package/dist/datasource/record.js

@@ -15,6 +15,11 @@ const dsUrl = (actionId) => {
 	if (!applicationId) panic("SOFTR_APPLICATION_ID is not set.");
 	return `${withoutTrailingSlash(datasourceApiUrl)}/v1/datasource/vibe/applications/${applicationId}/actions/${actionId}`;
 };
+async function describeFailure(res) {
+	const body = await res.json().catch(() => null);
+	const message = typeof body === "object" && body !== null && "message" in body ? body.message : null;
+	return typeof message === "string" && message.length > 0 ? `${res.status} ${message}` : `${res.status}`;
+}
 /**
 * Queries a list of records from the datasource.
 *
@@ -87,7 +92,7 @@ async function executeList(query, args) {
 			}
 		})
 	});
-	if (!res.ok) throw new Error(`Softr datasource list failed for "${actionId}": ${res.status}`);
+	if (!res.ok) throw new Error(`datasource list failed for "${actionId}": ${await describeFailure(res)}`);
 	const payload = await res.json();
 	const nextOffset = payload.offset < payload.total ? payload.offset : null;
 	return {
@@ -153,7 +158,7 @@ async function executeGet(query, id, filters) {
 			filterCriteria
 		})
 	});
-	if (!res.ok) throw new Error(`Softr datasource get failed for action "${actionId}": ${res.status}`);
+	if (!res.ok) throw new Error(`datasource get failed for action "${actionId}": ${await describeFailure(res)}`);
 	const contentLength = res.headers.get("Content-Length");
 	if (contentLength && parseInt(contentLength, 10) === 0) return null;
 	const record = await res.json();
@@ -182,7 +187,7 @@ async function createRecord(action, options) {
 		},
 		body: JSON.stringify({ fields: rawFields })
 	});
-	if (!res.ok) throw new Error(`Softr datasource create failed for action "${actionId}": ${res.status}`);
+	if (!res.ok) throw new Error(`datasource create failed for action "${actionId}": ${await describeFailure(res)}`);
 	const record = await res.json();
 	return {
 		id: record.id,
@@ -199,7 +204,7 @@ async function createRecord(action, options) {
 * })
 */
 async function updateRecord(action, options) {
-	if (!options.id) throw new Error(`Softr datasource update: id must not be empty`);
+	if (!options.id) throw new Error(`datasource update: id must not be empty`);
 	const { actionId, select } = resolveTarget(action, "update");
 	const data = options.data;
 	const rawFields = dealiasData(data, select);
@@ -211,7 +216,7 @@ async function updateRecord(action, options) {
 		},
 		body: JSON.stringify({ fields: rawFields })
 	});
-	if (!res.ok) throw new Error(`Softr datasource update failed for action "${actionId}": ${res.status}`);
+	if (!res.ok) throw new Error(`datasource update failed for action "${actionId}": ${await describeFailure(res)}`);
 	const record = await res.json();
 	return {
 		id: record.id,
@@ -230,7 +235,7 @@ async function deleteRecord(action, options) {
 		method: "DELETE",
 		headers: { Authorization: `Bearer ${readSessionToken()}` }
 	});
-	if (!res.ok) throw new Error(`Softr datasource delete failed for action "${actionId}": ${res.status}`);
+	if (!res.ok) throw new Error(`datasource delete failed for action "${actionId}": ${await describeFailure(res)}`);
 }
 function resolveTarget(subject, operation) {
 	const declaredBy = operation === "read" ? "defineQuery" : "defineMutation";
@@ -257,4 +262,4 @@ function withoutTrailingSlash(url) {
 }
 
 //#endregion
-export { createRecord, deleteRecord, dsUrl, getRecord, listRecords, resolveTarget, updateRecord };
+export { createRecord, deleteRecord, describeFailure, dsUrl, getRecord, listRecords, resolveTarget, updateRecord };

package/dist/index.d.ts

@@ -3,9 +3,10 @@ import { ActionPermissions, SoftrDatasources, defineIntegration, defineMutation,
 import { FileAttachment } from "./core/file-upload.js";
 import { FileItem, useFileUpload } from "./core/use-file-upload.js";
 import { SoftrContext } from "./auth/context.js";
-import { defineVisibility, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./routes/visibility.js";
-import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions } from "./auth/isomorphic.js";
-import { softrMcpMiddleware } from "./mcp.js";
+import { checkAccess, defineVisibility, isAuthorized } from "./visibility/visibility.js";
+import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./visibility/route.js";
+import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser } from "./auth/isomorphic.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
-export { type ActionPermissions, DefaultErrorOverlay, type FileAttachment, type FileItem, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, usePermissions, useUserTimezone };
+import { Audience } from "./visibility/audience.js";
+export { type ActionPermissions, Audience, DefaultErrorOverlay, type FileAttachment, type FileItem, type SoftrContext, type SoftrDatasources, type SoftrUserGroupId, type SoftrUserGroups, type User, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, useFileUpload, useUserTimezone };

package/dist/index.js

@@ -1,9 +1,10 @@
 import { useFileUpload } from "./core/use-file-upload.js";
 import { defineIntegration, defineMutation, defineQuery, defineWorkflow } from "./action.js";
-import { defineVisibility, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./routes/visibility.js";
-import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser, usePermissions } from "./auth/isomorphic.js";
-import { softrMcpMiddleware } from "./mcp.js";
+import { checkAccess, defineVisibility, isAuthorized } from "./visibility/visibility.js";
+import { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError } from "./visibility/route.js";
+import { getSoftrContext, initialSoftrContext, softrAuthMiddleware, useCurrentUser } from "./auth/isomorphic.js";
 import { useUserTimezone } from "./timezone.js";
 import { DefaultErrorOverlay } from "./default-error-overlay.js";
+import { Audience } from "./visibility/audience.js";
 
-export { DefaultErrorOverlay, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, softrMcpMiddleware, useCurrentUser, useFileUpload, usePermissions, useUserTimezone };
+export { Audience, DefaultErrorOverlay, assertRouteAccess, checkAccess, defineIntegration, defineMutation, defineQuery, defineVisibility, defineWorkflow, getSoftrContext, guardRoute, initialSoftrContext, isAccessError, isAlreadyAuthenticatedError, isAuthorized, isForbiddenError, isUnauthenticatedError, softrAuthMiddleware, useCurrentUser, useFileUpload, useUserTimezone };

package/dist/package.js

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

package/dist/server.js

@@ -1,6 +1,6 @@
 import { upload } from "./core/file-upload.js";
-import { ds } from "./datasource/datasource.js";
 import { auth } from "./auth/server.js";
+import { ds } from "./datasource/datasource.js";
 import { workflow } from "./core/workflow.js";
 import { integration } from "./core/integration.js";
 import "@tanstack/react-start/server-only";

package/dist/visibility/audience.d.ts

@@ -0,0 +1,31 @@
+import { Visibility } from "./visibility.js";
+import { ReactNode } from "react";
+
+//#region src/visibility/audience.d.ts
+type Props = {
+  visibility: Visibility;
+  children: ReactNode;
+  fallback?: ReactNode;
+};
+/**
+ * Renders `children` to the visitors a rule admits, and `fallback` to the rest.
+ *
+ * Use it to hide parts of the tree. The UI for visibility is accessible by the
+ * builder in Studio.
+ *
+ * Requires the root route to resolve {@link getSoftrContext}.
+ *
+ * @example
+ * const membersOnly = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
+ *
+ * <Audience visibility={membersOnly} fallback={<Upgrade />}>
+ *   <DangerZone />
+ * </Audience>
+ */
+declare function Audience({
+  visibility,
+  children,
+  fallback
+}: Props): ReactNode;
+//#endregion
+export { Audience };

package/dist/visibility/audience.js

@@ -0,0 +1,25 @@
+import { checkAccess } from "./visibility.js";
+import { useCurrentUser } from "../auth/isomorphic.js";
+
+//#region src/visibility/audience.tsx
+/**
+* Renders `children` to the visitors a rule admits, and `fallback` to the rest.
+*
+* Use it to hide parts of the tree. The UI for visibility is accessible by the
+* builder in Studio.
+*
+* Requires the root route to resolve {@link getSoftrContext}.
+*
+* @example
+* const membersOnly = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
+*
+* <Audience visibility={membersOnly} fallback={<Upgrade />}>
+*   <DangerZone />
+* </Audience>
+*/
+function Audience({ visibility, children, fallback = null }) {
+	return checkAccess(visibility, { user: useCurrentUser() }).ok ? children : fallback;
+}
+
+//#endregion
+export { Audience };

package/dist/visibility/route.d.ts

@@ -0,0 +1,71 @@
+import { AccessContext, AccessReason, Narrowed, Visibility, VisibilityRule } from "./visibility.js";
+
+//#region src/visibility/route.d.ts
+
+/**
+ * What a guard does when it denies a visitor: redirect to a path, or throw an
+ * {@link AccessError} for the route's `errorComponent` to render. A bare string
+ * is shorthand for redirecting there.
+ */
+type AccessBehaviour = string | {
+  strategy: "redirect";
+  to: string;
+} | {
+  strategy: "throw";
+};
+/** Per-reason overrides of the default {@link AccessBehaviour}. */
+type GuardOverrides = Partial<Record<AccessReason, AccessBehaviour>>;
+/**
+ * The access error a guard throws. It is plain data, not an `Error` subclass, so
+ * take it as `unknown` in an `errorComponent` and narrow it with
+ * {@link isAccessError}. It carries the reason and nothing else: the error is
+ * serialized into the page, so it never names the groups the route wanted.
+ *
+ * @example
+ * errorComponent: ({ error }: { error: unknown }) =>
+ *   isAccessError(error) ? <NoAccess /> : <AppError />
+ */
+type AccessError = {
+  type: "access_error";
+  reason: AccessReason;
+};
+/**
+ * True for any access error thrown by a guard, whatever its reason.
+ *
+ * An access error arrives as `unknown` — hydrated from the page, or thrown by
+ * anything else at all — so every field is checked before it is narrowed.
+ */
+declare function isAccessError(error: unknown): error is AccessError;
+/** True for an access error thrown because nobody was signed in. */
+declare function isUnauthenticatedError(error: unknown): error is AccessError;
+/** True for an access error thrown because the visitor was in none of the groups. */
+declare function isForbiddenError(error: unknown): error is AccessError;
+/** True for an access error thrown because a signed-out-only route saw a user. */
+declare function isAlreadyAuthenticatedError(error: unknown): error is AccessError;
+/**
+ * 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.
+ *
+ * Throws a router redirect, so it belongs in `beforeLoad` and nowhere else.
+ *
+ * @example
+ * beforeLoad: guardRoute(visibility, { unauthenticated: "/sign-in" })
+ */
+declare function guardRoute(visibility: Visibility, overrides?: GuardOverrides): (opts: {
+  context: AccessContext;
+}) => 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" })
+ * }
+ */
+declare function assertRouteAccess<R extends VisibilityRule>(visibility: Visibility<R>, context: AccessContext): asserts context is Narrowed<R>;
+//#endregion
+export { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError };

package/dist/visibility/route.js

@@ -0,0 +1,83 @@
+import { panic } from "../assertions.js";
+import { ACCESS_REASONS, checkAccess } from "./visibility.js";
+import { redirect } from "@tanstack/react-router";
+
+//#region src/visibility/route.ts
+function isAccessReason(value) {
+	return ACCESS_REASONS.some((reason) => reason === value);
+}
+/**
+* True for any access error thrown by a guard, whatever its reason.
+*
+* An access error arrives as `unknown` — hydrated from the page, or thrown by
+* anything else at all — so every field is checked before it is narrowed.
+*/
+function isAccessError(error) {
+	if (typeof error !== "object" || error === null) return false;
+	if (!("type" in error) || error.type !== "access_error") return false;
+	return "reason" in error && isAccessReason(error.reason);
+}
+function isReason(error, reason) {
+	return isAccessError(error) && error.reason === reason;
+}
+/** True for an access error thrown because nobody was signed in. */
+function isUnauthenticatedError(error) {
+	return isReason(error, "unauthenticated");
+}
+/** True for an access error thrown because the visitor was in none of the groups. */
+function isForbiddenError(error) {
+	return isReason(error, "forbidden");
+}
+/** True for an access error thrown because a signed-out-only route saw a user. */
+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]);
+	const resolved = typeof behaviour === "string" ? {
+		strategy: "redirect",
+		to: behaviour
+	} : behaviour;
+	if (resolved.strategy === "redirect") return redirect({ to: resolved.to });
+	return {
+		type: "access_error",
+		reason
+	};
+}
+/**
+* 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.
+*
+* Throws a router redirect, so it belongs in `beforeLoad` and nowhere else.
+*
+* @example
+* beforeLoad: guardRoute(visibility, { unauthenticated: "/sign-in" })
+*/
+function guardRoute(visibility, overrides) {
+	return ({ context }) => {
+		const result = checkAccess(visibility, context);
+		if (result.ok) return;
+		throw thrownFor(result.reason, overrides);
+	};
+}
+/**
+* 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" })
+* }
+*/
+function assertRouteAccess(visibility, context) {
+	const result = checkAccess(visibility, context);
+	if (result.ok) return;
+	throw thrownFor(result.reason, void 0);
+}
+
+//#endregion
+export { assertRouteAccess, guardRoute, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError };

package/dist/visibility/visibility.d.ts

@@ -0,0 +1,76 @@
+import { SoftrUserGroupId, User } from "../auth/user.js";
+import { SoftrContext } from "../auth/context.js";
+
+//#region src/visibility/visibility.d.ts
+
+/**
+ * Who may see a route.
+ *
+ * - `ALL_USERS` — everyone, signed in or not.
+ * - `NON_LOGGED_IN_USERS` — signed-out visitors only.
+ * - `LOGGED_IN_USERS` — signed-in visitors; with `userGroupIds`, only members of
+ *   at least one of those groups.
+ */
+type VisibilityRule = {
+  userGroup: "ALL_USERS";
+} | {
+  userGroup: "NON_LOGGED_IN_USERS";
+} | {
+  userGroup: "LOGGED_IN_USERS";
+  userGroupIds?: Array<SoftrUserGroupId>;
+};
+declare const visibilityBrand: unique symbol;
+/** A rule {@link defineVisibility} has produced. */
+type Visibility<R extends VisibilityRule = VisibilityRule> = R & {
+  readonly [visibilityBrand]: "visibility";
+};
+/**
+ * Why a visitor was denied.
+ *
+ * - `unauthenticated` — the route needs a signed-in visitor and there is none.
+ * - `forbidden` — signed in, but in none of the groups the route names.
+ * - `alreadyAuthenticated` — the route is for signed-out visitors only.
+ */
+declare const ACCESS_REASONS: readonly ["unauthenticated", "forbidden", "alreadyAuthenticated"];
+type AccessReason = (typeof ACCESS_REASONS)[number];
+type AccessCheck = {
+  ok: true;
+} | {
+  ok: false;
+  reason: AccessReason;
+};
+/** The one field of {@link SoftrContext} every access check reads. */
+type AccessContext = Pick<SoftrContext, "user">;
+/** The decision and, when a visitor is denied, the reason. Throws nothing. */
+declare function checkAccess(visibility: Visibility, context: AccessContext): AccessCheck;
+type Narrowed<R extends VisibilityRule> = R extends {
+  userGroup: "LOGGED_IN_USERS";
+} ? AccessContext & {
+  user: User;
+} : R extends {
+  userGroup: "NON_LOGGED_IN_USERS";
+} ? AccessContext & {
+  user: null;
+} : AccessContext;
+/**
+ * Declares who may see a route or a region of the page.
+ *
+ * At module scope in a route file, with a literal rule: the build reads these
+ * declarations out of the source to publish the app's route visibility.
+ *
+ * @example
+ * const visibility = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
+ *
+ * export const Route = createFileRoute("/about")({
+ *   beforeLoad: guardRoute(visibility),
+ *   component: About,
+ * })
+ */
+declare function defineVisibility<const R extends VisibilityRule>(rule: R): Visibility<R>;
+/**
+ * Whether the visitor passes the rule, narrowing `context.user` where the rule
+ * allows it. Throws nothing, so it is safe in a component.
+ */
+declare function isAuthorized<R extends VisibilityRule>(visibility: Visibility<R>, context: AccessContext): context is Narrowed<R>;
+//#endregion
+export { AccessContext, AccessReason, Narrowed, Visibility, VisibilityRule, checkAccess, defineVisibility, isAuthorized };

package/dist/visibility/visibility.js

@@ -0,0 +1,63 @@
+//#region src/visibility/visibility.ts
+/**
+* Why a visitor was denied.
+*
+* - `unauthenticated` — the route needs a signed-in visitor and there is none.
+* - `forbidden` — signed in, but in none of the groups the route names.
+* - `alreadyAuthenticated` — the route is for signed-out visitors only.
+*/
+const ACCESS_REASONS = [
+	"unauthenticated",
+	"forbidden",
+	"alreadyAuthenticated"
+];
+/** The decision and, when a visitor is denied, the reason. Throws nothing. */
+function checkAccess(visibility, context) {
+	const { user } = context;
+	switch (visibility.userGroup) {
+		case "ALL_USERS": return { ok: true };
+		case "NON_LOGGED_IN_USERS": return user === null ? { ok: true } : {
+			ok: false,
+			reason: "alreadyAuthenticated"
+		};
+		case "LOGGED_IN_USERS": {
+			if (user === null) return {
+				ok: false,
+				reason: "unauthenticated"
+			};
+			const required = visibility.userGroupIds ?? [];
+			if (required.length === 0) return { ok: true };
+			return required.some((id) => user.userGroupIds.includes(id)) ? { ok: true } : {
+				ok: false,
+				reason: "forbidden"
+			};
+		}
+	}
+}
+/**
+* Declares who may see a route or a region of the page.
+*
+* At module scope in a route file, with a literal rule: the build reads these
+* declarations out of the source to publish the app's route visibility.
+*
+* @example
+* const visibility = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
+*
+* export const Route = createFileRoute("/about")({
+*   beforeLoad: guardRoute(visibility),
+*   component: About,
+* })
+*/
+function defineVisibility(rule) {
+	return rule;
+}
+/**
+* Whether the visitor passes the rule, narrowing `context.user` where the rule
+* allows it. Throws nothing, so it is safe in a component.
+*/
+function isAuthorized(visibility, context) {
+	return checkAccess(visibility, context).ok;
+}
+
+//#endregion
+export { ACCESS_REASONS, checkAccess, defineVisibility, isAuthorized };