@hawkvision09/sso

Drop-in SSO authentication for all Woxin Next.js applications.
One package → consistent auth across every app.

Setup (3 steps)

1. Install

# 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

const nextConfig = {
  transpilePackages: ["@hawkvision09/sso"],
};
export default nextConfig;

3. Set environment variables

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)

import { createMiddlewareHandler } from "@hawkvision09/sso";
export const middleware = createMiddlewareHandler();
export const config = { matcher: ["/dashboard/:path*"] };

app/auth/callback/route.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

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

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

# 1. Login to npm
npm login

# 2. Build package
npm run build

# 3. Publish as public scoped package
npm publish --access public