npm package: @iterationroom/auth-wall
Description: Tiny, framework-agnostic auth wall client for Iteration Room SSO.
Author: Iteration Room
Latest version: 0.1.2

# @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

```bash
npm install @iterationroom/auth-wall
```

## Environment variables

By default, the auth wall redirects to:

```text
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:

```bash
VITE_IR_AUTH_URL=https://auth.iterationroom.com
```

In a Next.js app, you might set:

```bash
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:

```text
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:

```tsx
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:

```tsx
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:

```ts
// 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:

```ts
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.