@iterationroom/auth-wall

Client-side helper for protecting Iteration Room apps behind a centralized SSO “auth wall”.

This package:

• Detects the presence of the ir_session_presence cookie set by the Iteration Room SSO.
• Redirects unauthenticated users to https://auth.iterationroom.com (or a configured auth URL) with a redirect_back parameter.
• Provides tiny helpers for:
  • React SPAs (e.g. Vite) via a useAuthWall hook.
  • Next.js apps via middleware.ts.

The actual login flow is handled entirely by your central SSO app.

Installation

npm install @iterationroom/auth-wall

Environment variables

By default, the auth wall redirects to:

https://auth.iterationroom.com

You can override this via environment variables, resolved in this order:

1. VITE_IR_AUTH_URL
2. NEXT_PUBLIC_IR_AUTH_URL
3. Fallback: https://auth.iterationroom.com

In a Vite app, you might set:

VITE_IR_AUTH_URL=https://auth.iterationroom.com

In a Next.js app, you might set:

NEXT_PUBLIC_IR_AUTH_URL=https://auth.iterationroom.com

How it works conceptually

• Your central SSO app is hosted at https://auth.iterationroom.com.
• On successful login, it sets two cookies on the shared domain (e.g. .iterationroom.com):
  • ir_session (HttpOnly, signed, for server-side use).
  • ir_session_presence=1 (non-HttpOnly, readable by browsers).
• The SSO app then redirects back with a redirect_back query parameter, for example:

https://auth.iterationroom.com?redirect_back=https%3A%2F%2Fbwizer.iterationroom.com

This package does not implement login itself. It simply:

• Looks for ir_session_presence=1.
• If missing, redirects the user to the central SSO URL with the current URL as redirect_back.

React SPA usage (e.g. Vite)

For a React SPA, you can use the useAuthWall hook to protect your entire app:

import { useAuthWall } from "@iterationroom/auth-wall";

export default function App() {
  // On mount, if the ir_session_presence cookie is missing, the user will
  // be redirected to the central SSO, with the current URL as redirect_back.
  useAuthWall();

  return <YourApp />;
}

You can also conditionally enable it:

useAuthWall({ enabled: process.env.NODE_ENV === "production" });

The hook is SSR-safe because it only touches browser APIs inside useEffect.

Next.js usage via middleware

In a Next.js app (v14 or v15), you can use the requireAuth helper in your middleware.ts to protect routes:

// middleware.ts
import type { NextRequest } from "next/server";
import { requireAuth } from "@iterationroom/auth-wall/next-middleware";

export function middleware(req: NextRequest) {
  return requireAuth(req);
}

export const config = {
  matcher: ["/((?!public|_next/static|_next/image|favicon.ico).*)"],
};

Behavior:

• If the ir_session_presence cookie is present with value 1, the middleware calls NextResponse.next() and the request proceeds.
• If the cookie is missing, the middleware:
  • Builds redirect_back from the full requested URL (path + query).
  • Redirects to AUTH_BASE_URL?redirect_back=<encodedUrl>.

Low-level browser helpers

If you want to use the low-level functions directly (e.g. in vanilla JS or another framework), you can import from the main entry:

import {
  AUTH_BASE_URL,
  buildLoginUrl,
  redirectToAuth,
  hasSessionInBrowser,
} from "@iterationroom/auth-wall";

// Construct a login URL for an arbitrary location:
const url = buildLoginUrl(window.location.href);

// Imperatively trigger a redirect to the SSO:
redirectToAuth();

// Check whether the ir_session_presence cookie is present:
const hasSession = hasSessionInBrowser();

Exports

• From the main entry (@iterationroom/auth-wall):
  • AUTH_BASE_URL
  • SESSION_PRESENCE_COOKIE
  • buildLoginUrl(currentUrl: string): string
  • redirectToAuth(currentUrl?: string): void
  • hasSessionInBrowser(): boolean
  • useAuthWall(options?: { enabled?: boolean }): void
• From the Next.js-specific entry (@iterationroom/auth-wall/next-middleware):
  • requireAuth(req: NextRequest): NextResponse

Notes

• This package is intentionally small and framework-agnostic.
• It assumes your SSO app is responsible for actually creating and validating sessions.
• All it cares about is the presence of ir_session_presence=1 and redirecting when that cookie is missing.