@softr/sdk 0.0.45-alpha.0 → 0.0.45

package/dist/routes/visibility.d.ts

@@ -1,142 +0,0 @@
-import { SoftrUserGroupId, User } from "../auth/user.js";
-import { SoftrContext } from "../auth/context.js";
-
-//#region src/routes/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 RouteVisibility = {
-  userGroup: "ALL_USERS";
-} | {
-  userGroup: "NON_LOGGED_IN_USERS";
-} | {
-  userGroup: "LOGGED_IN_USERS";
-  userGroupIds?: Array<SoftrUserGroupId>;
-};
-/**
- * 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];
-/**
- * What a guard does when it refuses 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 result of {@link VisibilityHandle.check}: passed, or denied with a reason. */
-type AccessCheck = {
-  ok: true;
-} | {
-  ok: false;
-  reason: AccessReason;
-};
-/** The one field of {@link SoftrContext} every access check reads. */
-type AccessContext = Pick<SoftrContext, "user">;
-/** Decides whether a visitor passes a visibility rule, without throwing. */
-
-/**
- * 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;
-type Narrowed<R extends RouteVisibility> = R extends {
-  userGroup: "LOGGED_IN_USERS";
-} ? AccessContext & {
-  user: User;
-} : R extends {
-  userGroup: "NON_LOGGED_IN_USERS";
-} ? AccessContext & {
-  user: null;
-} : AccessContext;
-/** The four ways to apply a rule, returned by {@link defineVisibility}. */
-type VisibilityHandle<R extends RouteVisibility = RouteVisibility> = {
-  /**
-   * A `beforeLoad` handler that denies a visitor who fails the rule.
-   *
-   * By default an unauthenticated visitor is redirected to `/login`, an already
-   * signed-in one to `/`, and a forbidden one gets an {@link AccessError} thrown
-   * in place, for the route's `errorComponent` to render. Pass `overrides` to
-   * change what any one reason does.
-   *
-   * @example
-   * beforeLoad: visibility.guard({ unauthenticated: "/sign-in" })
-   */
-  guard(overrides?: GuardOverrides): (opts: {
-    context: AccessContext;
-  }) => void;
-  /**
-   * Throws the same access error or redirect `guard()` would, for code that
-   * needs to run its own checks after the rule.
-   *
-   * @example
-   * beforeLoad: ({ context }) => {
-   *   visibility.assert(context)
-   *   if (context.user.trialExpired) throw redirect({ to: "/renew" })
-   * }
-   */
-  assert(context: AccessContext): void;
-  /**
-   * Whether the visitor passes the rule. Narrows `context.user` where the rule
-   * allows it.
-   */
-  isAuthorized(context: AccessContext): context is Narrowed<R>;
-  /** The decision and, when a visitor is refused, the reason. Throws nothing. */
-  check(context: AccessContext): AccessCheck;
-};
-/**
- * Declares who may see a route, and returns the handle that enforces it.
- *
- * One call per route file, at module scope: the build reads these declarations
- * to publish the app's route visibility, so the rule must be a literal.
- *
- * @example
- * const visibility = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
- *
- * export const Route = createFileRoute("/about")({
- *   beforeLoad: visibility.guard(),
- *   component: About,
- * })
- */
-declare function defineVisibility<const R extends RouteVisibility>(rule: R): VisibilityHandle<R>;
-//#endregion
-export { defineVisibility, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError };

package/dist/routes/visibility.js

@@ -1,115 +0,0 @@
-import { panic } from "../assertions.js";
-import { redirect } from "@tanstack/react-router";
-
-//#region src/routes/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"
-];
-/** Decides whether a visitor passes a visibility rule, without throwing. */
-function checkAccess(rule, context) {
-	const { user } = context;
-	switch (rule.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 = rule.userGroupIds ?? [];
-			if (required.length === 0) return { ok: true };
-			return required.some((id) => user.userGroupIds.includes(id)) ? { ok: true } : {
-				ok: false,
-				reason: "forbidden"
-			};
-		}
-	}
-}
-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;
-	const candidate = error;
-	if (candidate.type !== "access_error") return false;
-	return isAccessReason(candidate.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
-	};
-}
-/**
-* Declares who may see a route, and returns the handle that enforces it.
-*
-* One call per route file, at module scope: the build reads these declarations
-* to publish the app's route visibility, so the rule must be a literal.
-*
-* @example
-* const visibility = defineVisibility({ userGroup: "LOGGED_IN_USERS" })
-*
-* export const Route = createFileRoute("/about")({
-*   beforeLoad: visibility.guard(),
-*   component: About,
-* })
-*/
-function defineVisibility(rule) {
-	return {
-		guard: (overrides) => ({ context }) => {
-			const result = checkAccess(rule, context);
-			if (result.ok) return;
-			throw thrownFor(result.reason, overrides);
-		},
-		assert: (context) => {
-			const result = checkAccess(rule, context);
-			if (result.ok) return;
-			throw thrownFor(result.reason, void 0);
-		},
-		isAuthorized: (context) => checkAccess(rule, context).ok,
-		check: (context) => checkAccess(rule, context)
-	};
-}
-
-//#endregion
-export { defineVisibility, isAccessError, isAlreadyAuthenticatedError, isForbiddenError, isUnauthenticatedError };

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

@@ -1,74 +0,0 @@
----
-name: mcp
-description: >-
-  Open the app to AI assistants over MCP: softrMcpMiddleware({ actions }) from
-  @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 honour a `redirect` search param, or the approval step dead-ends.
-metadata:
-  type: sub-skill
-  library: softr-sdk
-  library_version: 0.0.44
----
-
-**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.
-
-# MCP
-
-An app can answer an AI assistant on its own origin. The assistant signs in as an ordinary app user, and the actions you list become the tools it may call. Not wired by default — a new app serves no MCP endpoint until you add the middleware.
-
-## Setup
-
-```ts
-// src/start.ts
-import { createCsrfMiddleware, createStart } from '@tanstack/react-start'
-import { softrAuthMiddleware, softrMcpMiddleware } from '@softr/sdk'
-import { listCafes, addCafe } from './actions'
-
-export const startInstance = createStart(() => ({
-  requestMiddleware: [
-    createCsrfMiddleware({ filter: (ctx) => ctx.handlerType === 'serverFn' }),
-    softrMcpMiddleware({ actions: [listCafes, addCafe] }),
-    softrAuthMiddleware(),
-  ],
-}))
-```
-
-Order is part of the contract. `softrMcpMiddleware` goes **before** `softrAuthMiddleware`: an assistant arrives with a token, not a browser session, so it must not hit the session lookup first.
-
-## Choosing the actions
-
-The list is the whole tool surface. Write it out:
-
-- An action you leave out is invisible to the assistant, even where the app's pages use it freely.
-- An action you list still obeys its own `permissions`. Listing it does not widen who may run it — the assistant runs as whoever signed in, with that user's groups.
-- Two actions with the same `id` throw at startup. So does anything that is not a `defineQuery` or `defineMutation` value.
-
-Reads first. Add a write only when the user asked for one, and name it back to them.
-
-## 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 `/login` with a `redirect` search param holding where to come back to.
-
-**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 — not a full URL, not one starting `//`. 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.
-
-## 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.
-
-**Registering after `softrAuthMiddleware`.** The assistant's token is never read. Put the MCP middleware first.
-
-**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 `redirect` unchecked.** Anything that is not a path on this app is someone else's page. Reject it, fall back to `/`.
-
-## References
-
-- [record-queries/SKILL.md](../record-queries/SKILL.md): declaring the read actions you expose
-- [record-mutations/SKILL.md](../record-mutations/SKILL.md): declaring the write actions you expose
-- [auth/SKILL.md](../auth/SKILL.md): the sign-in and second-factor flows the round trip passes through