@nifrajs/auth 2.13.0 → 3.1.0

package/dist/authorization.d.ts

@@ -1,7 +1,4 @@
-/**
- * Public authorization seam. Nifra supplies the control-flow contract; the application or data layer
- * supplies the actual policy. No subject/resource data is persisted or interpreted here.
- */
+/** What a policy is asked to decide: this subject, doing this action, optionally to this resource. */
 export interface AuthorizationRequest<Subject = unknown, Resource = unknown> {
     readonly subject: Subject;
     readonly action: string;
@@ -10,6 +7,10 @@ export interface AuthorizationRequest<Subject = unknown, Resource = unknown> {
 export type Authorizer<Subject = unknown, Resource = unknown> = (request: AuthorizationRequest<Subject, Resource>) => boolean | Promise<boolean>;
 /** Evaluate a policy, failing closed for any non-true result. */
 export declare function isAuthorized<Subject, Resource>(authorizer: Authorizer<Subject, Resource>, request: AuthorizationRequest<Subject, Resource>): Promise<boolean>;
-/** Require an application/data-layer policy to allow an action; denied requests throw a 403 Response. */
+/** Require an application/data-layer policy to allow an action. A denied request throws a plain
+ * `status(403)` render - the same control-flow signal a guard throws, on the same rendering lane as a
+ * returned one, so the denial never builds a `Response`. Like the guards, it throws because it is
+ * called for effect from inside the work it protects; where the caller can return, return
+ * `status(403, ...)` instead. */
 export declare function requireAuthorization<Subject, Resource>(authorizer: Authorizer<Subject, Resource>, request: AuthorizationRequest<Subject, Resource>): Promise<void>;
 //# sourceMappingURL=authorization.d.ts.map

package/dist/authorization.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authorization.d.ts","sourceRoot":"","sources":["../src/authorization.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,oBAAoB,CAAC,OAAO,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO;IACzE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAC7B;AAED,MAAM,MAAM,UAAU,CAAC,OAAO,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO,IAAI,CAC9D,OAAO,EAAE,oBAAoB,CAAC,OAAO,EAAE,QAAQ,CAAC,KAC7C,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;AAE/B,iEAAiE;AACjE,wBAAsB,YAAY,CAAC,OAAO,EAAE,QAAQ,EAClD,UAAU,EAAE,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,EACzC,OAAO,EAAE,oBAAoB,CAAC,OAAO,EAAE,QAAQ,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC,CAElB;AAED,yGAAyG;AACzG,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,QAAQ,EAC1D,UAAU,EAAE,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,EACzC,OAAO,EAAE,oBAAoB,CAAC,OAAO,EAAE,QAAQ,CAAC,GAC/C,OAAO,CAAC,IAAI,CAAC,CAGf"}
+{"version":3,"file":"authorization.d.ts","sourceRoot":"","sources":["../src/authorization.ts"],"names":[],"mappings":"AAMA,sGAAsG;AACtG,MAAM,WAAW,oBAAoB,CAAC,OAAO,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO;IACzE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;IACzB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAA;CAC7B;AAED,MAAM,MAAM,UAAU,CAAC,OAAO,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO,IAAI,CAC9D,OAAO,EAAE,oBAAoB,CAAC,OAAO,EAAE,QAAQ,CAAC,KAC7C,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;AAE/B,iEAAiE;AACjE,wBAAsB,YAAY,CAAC,OAAO,EAAE,QAAQ,EAClD,UAAU,EAAE,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,EACzC,OAAO,EAAE,oBAAoB,CAAC,OAAO,EAAE,QAAQ,CAAC,GAC/C,OAAO,CAAC,OAAO,CAAC,CAElB;AAED;;;;iCAIiC;AACjC,wBAAsB,oBAAoB,CAAC,OAAO,EAAE,QAAQ,EAC1D,UAAU,EAAE,UAAU,CAAC,OAAO,EAAE,QAAQ,CAAC,EACzC,OAAO,EAAE,oBAAoB,CAAC,OAAO,EAAE,QAAQ,CAAC,GAC/C,OAAO,CAAC,IAAI,CAAC,CAGf"}

package/dist/authorization.js

@@ -1,11 +1,20 @@
+/**
+ * Public authorization seam. Nifra supplies the control-flow contract; the application or data layer
+ * supplies the actual policy. No subject/resource data is persisted or interpreted here.
+ */
+import { status } from "@nifrajs/core/server";
 /** Evaluate a policy, failing closed for any non-true result. */
 export async function isAuthorized(authorizer, request) {
     return (await authorizer(request)) === true;
 }
-/** Require an application/data-layer policy to allow an action; denied requests throw a 403 Response. */
+/** Require an application/data-layer policy to allow an action. A denied request throws a plain
+ * `status(403)` render - the same control-flow signal a guard throws, on the same rendering lane as a
+ * returned one, so the denial never builds a `Response`. Like the guards, it throws because it is
+ * called for effect from inside the work it protects; where the caller can return, return
+ * `status(403, ...)` instead. */
 export async function requireAuthorization(authorizer, request) {
     if (await isAuthorized(authorizer, request))
         return;
-    throw Response.json({ ok: false, error: "forbidden" }, { status: 403 });
+    throw status(403, { ok: false, error: "forbidden" });
 }
 //# sourceMappingURL=authorization.js.map

package/dist/authorization.js.map

@@ -1 +1 @@
-{"version":3,"file":"authorization.js","sourceRoot":"","sources":["../src/authorization.ts"],"names":[],"mappings":"AAcA,iEAAiE;AACjE,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,UAAyC,EACzC,OAAgD;IAEhD,OAAO,CAAC,MAAM,UAAU,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,CAAA;AAC7C,CAAC;AAED,yGAAyG;AACzG,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,UAAyC,EACzC,OAAgD;IAEhD,IAAI,MAAM,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC;QAAE,OAAM;IACnD,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;AACzE,CAAC"}
+{"version":3,"file":"authorization.js","sourceRoot":"","sources":["../src/authorization.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAA;AAa7C,iEAAiE;AACjE,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,UAAyC,EACzC,OAAgD;IAEhD,OAAO,CAAC,MAAM,UAAU,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,CAAA;AAC7C,CAAC;AAED;;;;iCAIiC;AACjC,MAAM,CAAC,KAAK,UAAU,oBAAoB,CACxC,UAAyC,EACzC,OAAgD;IAEhD,IAAI,MAAM,YAAY,CAAC,UAAU,EAAE,OAAO,CAAC;QAAE,OAAM;IACnD,MAAM,MAAM,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAA;AACtD,CAAC"}

package/dist/guards.d.ts

@@ -1,9 +1,3 @@
-/**
- * Route guards - run at the top of a protected loader/action/handler. On a missing session they
- * **throw a `Response`** (a 302 to your login path, or a 401); nifra returns a thrown Response as-is, so
- * the guard short-circuits the rest of the handler. Pairs with `@nifrajs/auth` sessions but only needs the
- * `Session` shape, so it's framework-agnostic.
- */
 import type { Session } from "./session.js";
 /** What a guard does when the check fails: 302 to `redirectTo` (a same-origin path), or - omitted - a
  * 401 JSON (`{ ok: false, error: "unauthorized" }`). */
@@ -11,7 +5,8 @@ export interface GuardOptions {
     readonly redirectTo?: string;
 }
 /**
- * Require a non-empty session. Returns it when present; otherwise throws a `Response` (302/401). Use at
+ * Require a non-empty session. Returns it when present; otherwise throws a `status(...)` render
+ * (302/401) - control flow, not a `Response`; see the module docs above. Use at
  * the top of a protected loader:
  * `const session = requireSession(await sessions.get(c), { redirectTo: "/login" })`.
  */

package/dist/guards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAE3C;wDACwD;AACxD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAiBD;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,EACtB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,EACpF,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,EACtB,GAAG,EAAE,CAAC,EACN,OAAO,GAAE,YAAiB,GACzB,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAKtB"}
+{"version":3,"file":"guards.d.ts","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAE3C;wDACwD;AACxD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B;AAgBD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACjE,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,EACtB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,IAAI,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,SAAS,MAAM,IAAI,EACpF,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,EACtB,GAAG,EAAE,CAAC,EACN,OAAO,GAAE,YAAiB,GACzB,WAAW,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAKtB"}

package/dist/guards.js

@@ -1,17 +1,33 @@
+/**
+ * Route guards - run at the top of a protected loader/action/handler. On a missing session they
+ * **throw** a `status(...)` render (a 302 to your login path, or a 401); nifra treats a thrown
+ * `status(...)` as control flow and renders it on the ordinary plain-data lane, so the guard
+ * short-circuits the rest of the handler at the cost of a normal return, without a `Response` being
+ * built or drained.
+ *
+ * The throw is the point of a guard: `requireSession(...)` is called for effect from inside the
+ * handler, so its caller cannot return the rejection on its behalf - only unwinding gets out of a
+ * half-finished handler. Everywhere the caller CAN return - a `beforeHandle`, a `derive`, the handler
+ * itself - return `status(...)` instead; see its docs.
+ *
+ * Pairs with `@nifrajs/auth` sessions but only needs the `Session` shape, so it's framework-agnostic.
+ */
+import { isSameOriginPath, status } from "@nifrajs/core/server";
 const rejection = (options) => {
     const to = options.redirectTo;
-    if (to === undefined) {
-        return Response.json({ ok: false, error: "unauthorized" }, { status: 401 });
-    }
-    // Same-origin guard (mirrors @nifrajs/web `redirect`): a single leading "/", never "//host" or an
-    // absolute URL. `redirectTo` is dev-authored, so a bad value is a config bug - fail loud here.
-    if (!to.startsWith("/") || to.startsWith("//")) {
-        throw new Error(`[nifra/auth] guard redirectTo must be a same-origin path beginning with "/" (got ${JSON.stringify(to)})`);
+    if (to === undefined)
+        return status(401, { ok: false, error: "unauthorized" });
+    // The kernel's same-origin predicate, the one `@nifrajs/web`'s `redirect` uses: a single leading
+    // "/", never "//host", an absolute URL, or a form a URL parser resolves off-origin. `redirectTo`
+    // is dev-authored, so a bad value is a config bug - fail loud here.
+    if (!isSameOriginPath(to)) {
+        throw new Error(`[nifra/auth] guard redirectTo must be a same-origin path beginning with "/" - never "//", a backslash, or a control character (got ${JSON.stringify(to)})`);
     }
-    return new Response(null, { status: 302, headers: { location: to } });
+    return status(302, undefined, { headers: { location: to } });
 };
 /**
- * Require a non-empty session. Returns it when present; otherwise throws a `Response` (302/401). Use at
+ * Require a non-empty session. Returns it when present; otherwise throws a `status(...)` render
+ * (302/401) - control flow, not a `Response`; see the module docs above. Use at
  * the top of a protected loader:
  * `const session = requireSession(await sessions.get(c), { redirectTo: "/login" })`.
  */

package/dist/guards.js.map

@@ -1 +1 @@
-{"version":3,"file":"guards.js","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAcA,MAAM,SAAS,GAAG,CAAC,OAAqB,EAAY,EAAE;IACpD,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAA;IAC7B,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;QACrB,OAAO,QAAQ,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;IAC7E,CAAC;IACD,kGAAkG;IAClG,+FAA+F;IAC/F,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC/C,MAAM,IAAI,KAAK,CACb,oFAAoF,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,CAC1G,CAAA;IACH,CAAC;IACD,OAAO,IAAI,QAAQ,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;AACvE,CAAC,CAAA;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAsB,EACtB,UAAwB,EAAE;IAE1B,IAAI,CAAC,OAAO,CAAC,OAAO;QAAE,OAAO,OAAO,CAAA;IACpC,MAAM,SAAS,CAAC,OAAO,CAAC,CAAA;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,OAAsB,EACtB,GAAM,EACN,UAAwB,EAAE;IAE1B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC9B,uGAAuG;IACvG,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAA6B,CAAA;IAC/E,MAAM,SAAS,CAAC,OAAO,CAAC,CAAA;AAC1B,CAAC"}
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../src/guards.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,gBAAgB,EAAuB,MAAM,EAAE,MAAM,sBAAsB,CAAA;AASpF,MAAM,SAAS,GAAG,CAAC,OAAqB,EAAkB,EAAE;IAC1D,MAAM,EAAE,GAAG,OAAO,CAAC,UAAU,CAAA;IAC7B,IAAI,EAAE,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC,GAAG,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,cAAc,EAAE,CAAC,CAAA;IAC9E,iGAAiG;IACjG,iGAAiG;IACjG,oEAAoE;IACpE,IAAI,CAAC,gBAAgB,CAAC,EAAE,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CACb,sIAAsI,IAAI,CAAC,SAAS,CAAC,EAAE,CAAC,GAAG,CAC5J,CAAA;IACH,CAAC;IACD,OAAO,MAAM,CAAC,GAAG,EAAE,SAAS,EAAE,EAAE,OAAO,EAAE,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,CAAC,CAAA;AAC9D,CAAC,CAAA;AAED;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAsB,EACtB,UAAwB,EAAE;IAE1B,IAAI,CAAC,OAAO,CAAC,OAAO;QAAE,OAAO,OAAO,CAAA;IACpC,MAAM,SAAS,CAAC,OAAO,CAAC,CAAA;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CACzB,OAAsB,EACtB,GAAM,EACN,UAAwB,EAAE;IAE1B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC9B,uGAAuG;IACvG,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAA6B,CAAA;IAC/E,MAAM,SAAS,CAAC,OAAO,CAAC,CAAA;AAC1B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/auth",
-  "version": "2.13.0",
+  "version": "3.1.0",
   "description": "Session primitives for nifra - signed-cookie + server-store sessions, CSRF, and route guards. Bring your own identity (Better Auth / Lucia / OAuth); nifra owns the session.",
   "keywords": [
     "bun",
@@ -37,7 +37,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@nifrajs/core": "^2.13.0"
+    "@nifrajs/core": "^3.1.0"
   },
   "devDependencies": {
     "@nifrajs/core": "workspace:*"

package/src/authorization.ts

@@ -2,6 +2,9 @@
  * Public authorization seam. Nifra supplies the control-flow contract; the application or data layer
  * supplies the actual policy. No subject/resource data is persisted or interpreted here.
  */
+import { status } from "@nifrajs/core/server"
+
+/** What a policy is asked to decide: this subject, doing this action, optionally to this resource. */
 export interface AuthorizationRequest<Subject = unknown, Resource = unknown> {
   readonly subject: Subject
   readonly action: string
@@ -20,11 +23,15 @@ export async function isAuthorized<Subject, Resource>(
   return (await authorizer(request)) === true
 }
 
-/** Require an application/data-layer policy to allow an action; denied requests throw a 403 Response. */
+/** Require an application/data-layer policy to allow an action. A denied request throws a plain
+ * `status(403)` render - the same control-flow signal a guard throws, on the same rendering lane as a
+ * returned one, so the denial never builds a `Response`. Like the guards, it throws because it is
+ * called for effect from inside the work it protects; where the caller can return, return
+ * `status(403, ...)` instead. */
 export async function requireAuthorization<Subject, Resource>(
   authorizer: Authorizer<Subject, Resource>,
   request: AuthorizationRequest<Subject, Resource>,
 ): Promise<void> {
   if (await isAuthorized(authorizer, request)) return
-  throw Response.json({ ok: false, error: "forbidden" }, { status: 403 })
+  throw status(403, { ok: false, error: "forbidden" })
 }

package/src/guards.ts

@@ -1,9 +1,18 @@
 /**
  * Route guards - run at the top of a protected loader/action/handler. On a missing session they
- * **throw a `Response`** (a 302 to your login path, or a 401); nifra returns a thrown Response as-is, so
- * the guard short-circuits the rest of the handler. Pairs with `@nifrajs/auth` sessions but only needs the
- * `Session` shape, so it's framework-agnostic.
+ * **throw** a `status(...)` render (a 302 to your login path, or a 401); nifra treats a thrown
+ * `status(...)` as control flow and renders it on the ordinary plain-data lane, so the guard
+ * short-circuits the rest of the handler at the cost of a normal return, without a `Response` being
+ * built or drained.
+ *
+ * The throw is the point of a guard: `requireSession(...)` is called for effect from inside the
+ * handler, so its caller cannot return the rejection on its behalf - only unwinding gets out of a
+ * half-finished handler. Everywhere the caller CAN return - a `beforeHandle`, a `derive`, the handler
+ * itself - return `status(...)` instead; see its docs.
+ *
+ * Pairs with `@nifrajs/auth` sessions but only needs the `Session` shape, so it's framework-agnostic.
  */
+import { isSameOriginPath, type ResponseResult, status } from "@nifrajs/core/server"
 import type { Session } from "./session.ts"
 
 /** What a guard does when the check fails: 302 to `redirectTo` (a same-origin path), or - omitted - a
@@ -12,23 +21,23 @@ export interface GuardOptions {
   readonly redirectTo?: string
 }
 
-const rejection = (options: GuardOptions): Response => {
+const rejection = (options: GuardOptions): ResponseResult => {
   const to = options.redirectTo
-  if (to === undefined) {
-    return Response.json({ ok: false, error: "unauthorized" }, { status: 401 })
-  }
-  // Same-origin guard (mirrors @nifrajs/web `redirect`): a single leading "/", never "//host" or an
-  // absolute URL. `redirectTo` is dev-authored, so a bad value is a config bug - fail loud here.
-  if (!to.startsWith("/") || to.startsWith("//")) {
+  if (to === undefined) return status(401, { ok: false, error: "unauthorized" })
+  // The kernel's same-origin predicate, the one `@nifrajs/web`'s `redirect` uses: a single leading
+  // "/", never "//host", an absolute URL, or a form a URL parser resolves off-origin. `redirectTo`
+  // is dev-authored, so a bad value is a config bug - fail loud here.
+  if (!isSameOriginPath(to)) {
     throw new Error(
-      `[nifra/auth] guard redirectTo must be a same-origin path beginning with "/" (got ${JSON.stringify(to)})`,
+      `[nifra/auth] guard redirectTo must be a same-origin path beginning with "/" - never "//", a backslash, or a control character (got ${JSON.stringify(to)})`,
     )
   }
-  return new Response(null, { status: 302, headers: { location: to } })
+  return status(302, undefined, { headers: { location: to } })
 }
 
 /**
- * Require a non-empty session. Returns it when present; otherwise throws a `Response` (302/401). Use at
+ * Require a non-empty session. Returns it when present; otherwise throws a `status(...)` render
+ * (302/401) - control flow, not a `Response`; see the module docs above. Use at
  * the top of a protected loader:
  * `const session = requireSession(await sessions.get(c), { redirectTo: "/login" })`.
  */