KatebTech Auth

Shared authentication pages, action factories, session helpers, redirects, validation, and database setup utilities for Kateb Tech packages and websites.

Purpose

@katebtech/auth provides reusable authentication building blocks for Kateb Tech projects that need account login, password recovery, email verification, protected-route checks, and session cookie handling.

The package owns shared auth behaviour and UI. Consuming websites own their app routes, environment values, organisation profile, database URL, Resend API key, session key, and any website-specific server-action wrappers.

Package Overview

This package provides:

• authentication page components and forms;
• login, forgot-password, reset-password, and verification action factories;
• session cookie, JWT, and protected-route helpers;
• safe redirect helpers for authenticated areas;
• authentication form schemas and action state types;
• auth database table creation and seed helpers.

The package does not expose a root @katebtech/auth import. Consumers should import from the specific public subpath that owns the feature they need.

File Structure

src
├── auth
│   ├── _lib
│   │   ├── database
│   │   ├── redirects
│   │   ├── session
│   │   └── validation
│   ├── _ui
│   │   └── layout
│   ├── docs
│   ├── forgot-password
│   ├── login
│   ├── reset-password
│   ├── verification
│   └── index.ts

Feature folders expose their public API through local index.ts files. Implementation details stay inside feature folders or underscored internal folders.

Import Style

Use package subpaths when consuming public APIs:

import { AuthLoginPage, createLoginAction } from "@katebtech/auth/auth/login";
import { createForgotPasswordAction } from "@katebtech/auth/auth/forgot-password";
import { createResetPasswordAction } from "@katebtech/auth/auth/reset-password";
import {
  AuthVerifyEmailPage,
  createVerificationActions,
} from "@katebtech/auth/auth/verification";
import { buildLoginHrefWithNext } from "@katebtech/auth/auth/redirects";
import { AUTH_SESSION_CONFIG, getSession } from "@katebtech/auth/auth/session";

Inside this package, prefer relative imports between local files:

import type { AuthState } from "../_lib/validation";
import { buildLoginHrefWithNext } from "./loginRedirect";

Avoid importing this package from itself.

Package Rules

Public exports should include reusable components, action factories, helpers, and public types. Internal data-shaping types and implementation helpers should remain private unless another package has a clear need for them.

Auth page components that display website identity require the consuming website to pass its organisation name through orgName. The website should read this from its own organisation/profile source.

Action factories require website-owned configuration values. The consuming app should create server actions that close over values such as postgresUrl, resendApiKey, sessionEncodedKey, adminRootHref, and optional otherLanguageKey.

Protected route and redirect behaviour should use exported helpers instead of hard-coded cookie names or redirect sanitisation logic.

This package depends on shared lower-level Kateb Tech packages such as @katebtech/core, @katebtech/emails, and @katebtech/layout. It should not depend on website packages or higher-level page packages.

Module Documentation

Auth

Import path:

import { AuthLayout } from "@katebtech/auth/auth";

The auth barrel exports the reusable auth page components, action factories, shared layout UI, and public prop types from the login, forgot-password, reset-password, and verification modules.

Login

Import path:

import { AuthLoginPage, createLoginAction } from "@katebtech/auth/auth/login";

AuthLoginPage renders the shared login page. It requires orgName and a login action. It also accepts next and adminRootHref for authenticated redirects.

createLoginAction creates the server action used by the login form. It requires postgresUrl and sessionEncodedKey, and supports optional adminRootHref and securityCheck.

Forgot Password

Import path:

import {
  AuthForgotPasswordPage,
  createForgotPasswordAction,
} from "@katebtech/auth/auth/forgot-password";

AuthForgotPasswordPage renders the password recovery page. It requires orgName and an action.

createForgotPasswordAction creates the server action used to send recovery email. It requires postgresUrl and resendApiKey, and supports optional securityCheck and otherLanguageKey.

Reset Password

Import path:

import {
  AuthResetPasswordPage,
  createResetPasswordAction,
} from "@katebtech/auth/auth/reset-password";

AuthResetPasswordPage renders the reset-password page. It requires orgName and an action.

createResetPasswordAction creates the server action used to update a user's password. It requires postgresUrl.

Verification

Import path:

import {
  AuthVerifyEmailPage,
  createVerificationActions,
} from "@katebtech/auth/auth/verification";

AuthVerifyEmailPage renders the email verification page. It requires verifyAction and resendAction. It also accepts next, adminRootHref, and redirectOnMissingContextHref.

createVerificationActions creates verifyCode and resendCode server actions. It requires postgresUrl, resendApiKey, and sessionEncodedKey, and supports optional adminRootHref and otherLanguageKey.

Redirects

Import path:

import {
  buildLoginHrefWithNext,
  redirectToLoginWithNext,
  safeAdminNext,
} from "@katebtech/auth/auth/redirects";

Redirect helpers build login URLs with a next parameter, redirect protected requests to login, and sanitise admin redirect targets.

Session

Import path:

import {
  AUTH_SESSION_CONFIG,
  destroySession,
  getSession,
  isProtectedPath,
} from "@katebtech/auth/auth/session";

Session helpers create, read, verify, encrypt, decrypt, and destroy auth sessions. Protected-route helpers identify paths that require an authenticated session.

Validation

Import path:

import { authSchema } from "@katebtech/auth/auth/validation";
import type {
  AuthState,
  ResetPasswordState,
} from "@katebtech/auth/auth/validation";

Validation exports provide shared auth form schemas and public action state types for authentication flows.

Database

Import path:

import { createAuthTables, seedAuthUser } from "@katebtech/auth/auth/database";

Database helpers provide package-owned auth table setup and seed utilities. Additional database notes live in src/auth/docs/DATABASE.md.

Usage Example

Create website-owned server actions from the exported action factories:

"use server";

import { createForgotPasswordAction } from "@katebtech/auth/auth/forgot-password";
import { createLoginAction } from "@katebtech/auth/auth/login";
import { createResetPasswordAction } from "@katebtech/auth/auth/reset-password";
import { createVerificationActions } from "@katebtech/auth/auth/verification";
import { ORG_PROFILE } from "@/app/_lib/org/profile";
import { serverEnv } from "@/app/_lib/env/server";
import { sessionEncodedKey } from "@/app/_lib/sessionEncodedKey";

const loginAction = createLoginAction({
  postgresUrl: serverEnv.postgresUrl,
  sessionEncodedKey,
});

const forgotPasswordAction = createForgotPasswordAction({
  postgresUrl: serverEnv.postgresUrl,
  resendApiKey: serverEnv.resendApiKey,
  otherLanguageKey: ORG_PROFILE.otherLanguageKey,
});

const resetPasswordAction = createResetPasswordAction({
  postgresUrl: serverEnv.postgresUrl,
});

const verificationActions = createVerificationActions({
  postgresUrl: serverEnv.postgresUrl,
  resendApiKey: serverEnv.resendApiKey,
  sessionEncodedKey,
  otherLanguageKey: ORG_PROFILE.otherLanguageKey,
});

export const auth = loginAction;
export const forgotPassword = forgotPasswordAction;
export const resetPassword = resetPasswordAction;
export const resendCode = verificationActions.resendCode;
export const verifyCode = verificationActions.verifyCode;

Mount the shared pages in the consuming website's route tree:

import { AuthLoginPage } from "@katebtech/auth/auth/login";
import { ORG_PROFILE } from "@/app/_lib/org/profile";
import { auth } from "../../_lib/actions";

export default async function Page({
  searchParams,
}: {
  searchParams: Promise<{ next?: string }>;
}) {
  const { next } = await searchParams;

  return (
    <AuthLoginPage
      orgName={ORG_PROFILE.orgName}
      next={next}
      action={auth}
    />
  );
}