npm package: @hawkvision09/sso
Description: HawkVision SSO client library for Next.js applications. Drop-in auth for every HawkVision app.
Latest version: 1.0.2

# @hawkvision09/sso

Drop-in SSO authentication for all HawkVision Next.js applications.  
**One package → consistent auth across every app.**

---

## Setup (3 steps)

### 1. Install

```bash
# Local (development / monorepo)
npm install @hawkvision09/sso@file:../packages/@hawkvision09/sso-package

# Production (after publishing to npm)
npm install @hawkvision09/sso
```

### 2. Add to next.config.ts

```ts
const nextConfig = {
  transpilePackages: ["@hawkvision09/sso"],
};
export default nextConfig;
```

### 3. Set environment variables

```env
NEXT_PUBLIC_SSO_URL=http://localhost:3000
NEXT_PUBLIC_SSO_SERVICE_ID=your-service-uuid
NEXT_PUBLIC_SSO_REDIRECT_URI=http://localhost:3001/auth/callback
JWT_SECRET=your-32-char-secret
```

---

## Files to create in your app (copy-paste ready)

### proxy.ts (root of project)

```ts
import { createMiddlewareHandler } from "@hawkvision09/sso";
export const middleware = createMiddlewareHandler();
export const config = { matcher: ["/dashboard/:path*"] };
```

### app/auth/callback/route.ts

```ts
import { createCallbackHandler } from "@hawkvision09/sso";

// Allow ANY SSO-authenticated user:
export const GET = createCallbackHandler();

// OR gate behind extra check (e.g. tenant lookup):
export const GET = createCallbackHandler({
  async onAuthenticated(userInfo) {
    const tenant = await masterSheet.getTenantByEmail(userInfo.email);
    if (!tenant) throw new Error("Not a registered tenant");
    return { email: userInfo.email, roles: userInfo.roles ?? [] };
  },
});
```

### app/api/auth/session/route.ts

```ts
import { handleSessionRoute } from "@hawkvision09/sso";
import type { NextRequest } from "next/server";
export async function GET(req: NextRequest) {
  return handleSessionRoute(req);
}
```

### app/api/auth/logout/route.ts

```ts
import { handleLogoutRoute } from "@hawkvision09/sso";
import type { NextRequest } from "next/server";
export async function POST(req: NextRequest) {
  return handleLogoutRoute(req);
}
```

---

## API Reference

| Export                            | Where to use                       | Description                                                  |
| --------------------------------- | ---------------------------------- | ------------------------------------------------------------ |
| `createMiddlewareHandler()`       | `proxy.ts`                         | Returns middleware that protects routes and redirects to SSO |
| `createCallbackHandler(options?)` | `app/auth/callback/route.ts`       | Handles SSO code exchange, creates session                   |
| `handleSessionRoute(req)`         | `app/api/auth/session/route.ts`    | Returns current user session as JSON                         |
| `handleLogoutRoute(req)`          | `app/api/auth/logout/route.ts`     | Clears session, notifies SSO                                 |
| `getSession()`                    | Server Components, API Routes      | Reads JWT session from cookie                                |
| `checkSession()`                  | Client Components (`'use client'`) | Checks session via fetch                                     |
| `logout()`                        | Client Components (`'use client'`) | Clears session + SSO redirect                                |
| `buildSSOAuthUrl(state?)`         | Landing pages                      | Builds the SSO login URL                                     |

---

## Publishing

```bash
# 1. Login to npm
npm login

# 2. Build package
npm run build

# 3. Publish as public scoped package
npm publish --access public
```