@terraza/auth

Shared dashboard authentication for Terraza apps. Scrypt password verification, HMAC-SHA256 signed session tokens, and Next.js middleware — extracted from identical implementations across Shelf and Job Search.

Install

pnpm add @terraza/auth

Usage

Auth library (@terraza/auth)

Edge-compatible session functions and Node.js password verification.

import { createSession, verifySession, verifyPassword, envPasswordHash } from "@terraza/auth";

// Verify a password against a scrypt hash
const valid = await verifyPassword(password, hash);

// Create a signed session token (base64url JSON + HMAC-SHA256)
const token = await createSession({ secret: process.env.AUTH_SECRET! });

// With custom claims (multi-user)
const token = await createSession(
  { secret: process.env.AUTH_SECRET! },
  { sub: "user_123" },
);

// Verify a token — returns SessionPayload or null
const payload = await verifySession(token, { secret: process.env.AUTH_SECRET! });

Next.js helpers (@terraza/auth/next)

Cookie management and edge middleware for Next.js dashboards.

import { setSessionCookie, clearSessionCookie, createAuthMiddleware } from "@terraza/auth/next";

const config = { secret: process.env.AUTH_SECRET! };

// Set session cookie (Server Action or Route Handler)
await setSessionCookie(config);

// Clear session cookie
await clearSessionCookie(config);

// Create edge middleware
export const middleware = createAuthMiddleware({
  config,
  publicPaths: ["/api/public"],
});

Configuration

interface SessionConfig {
  secret: string;        // HMAC signing key
  maxAge?: number;       // Session duration in seconds (default: 7 days)
}

interface CookieConfig extends SessionConfig {
  cookieName?: string;   // Default: "session"
  secure?: boolean;      // Default: NODE_ENV === "production"
}

Token format

Tokens are base64url(JSON).hex(HMAC-SHA256) with an extensible JSON payload:

{ "exp": 1713100000000, "sub": "user_123" }

• exp — always present, set from maxAge
• sub — optional user identifier (for multi-user apps)
• Additional claims are passed through

Environment variables

| Variable | Purpose | |----------|---------| | AUTH_SECRET | HMAC-SHA256 signing key for session tokens | | AUTH_PASSWORD_HASH | Scrypt hash in salt:hexKey format (single-user mode) |

Edge compatibility

• createSession, verifySession — Web Crypto API, works on Edge Runtime
• verifyPassword — Node.js crypto.scrypt, server-side only
• createAuthMiddleware — runs on Edge Runtime