Auth

Zero-dependency authentication, user management, and notification system for SvelteKit. JWT sessions, WebAuthn passkeys, push notifications, and pre-built UI — all powered by Web Crypto API.

@urbicon-ui/auth provides everything you need for auth in a SvelteKit app: session management, registration with invitation gates, password reset flows, passkey login, real-time notifications, and push — with zero runtime dependencies.

All UI components use @urbicon-ui/blocks primitives, support unstyled / slotClasses / snippet overrides, and auto-detect locale from the @urbicon-ui/i18n context.

The complete reference — architecture, staged setup, federation (SSO), the adapter contract, and the known-limitations catalog with the production checklist — is the Auth Reference (AUTH.md), rendered from the same document that ships inside the npm package.

Architecture

Each auth flow has two sides: a UI component (client) and a handler factory (server). The UI components send fetch requests to your SvelteKit API routes. The handler factories create those endpoints with all security built in.

UI Component	Server Handler	Default Endpoint	What it does
LoginPage	createLoginHandler	/api/auth/login	PBKDF2 verify, lockout, JWT session
RegisterPage	createRegisterHandler	/api/auth/register	Invitation check, hash, verify email
ForgotPasswordPage	createForgotPasswordHandler	/api/auth/forgot-password	Token email, timing-safe
ResetPasswordPage	createResetPasswordHandler	/api/auth/reset-password	Token verify, re-hash
VerifyEmailPage	createVerifyEmailHandler	/api/auth/verify-email	SHA-256 token check
PasskeyManager	createPasskey*Handler	/api/auth/passkey/*	WebAuthn CBOR/COSE verify
InvitationManager	createInvitationHandlers	/api/invitations	authorize-gated CRUD
NotificationListener	createStreamHandler	/api/notifications/stream	SSE with keep-alive

All server handlers are imported from @urbicon-ui/auth/server. Database access is abstracted via the Adapter pattern — a Prisma adapter is included, custom adapters implement the repository interfaces.

Auth Pages

LoginPage

Management

InvitationManager

Admin panel for invitation-gated registration with email toggle.

PasskeyManager

WebAuthn credential management — register and delete passkeys.

AccountSettings

Self-service panel — change name, email and password, delete the account.

SessionManager

Active-session list with "this device" badge and per-session sign-out.

TwoFactorManager

TOTP two-factor enrolment, backup codes, and re-auth-gated disable.

Notifications

NotificationCenter

Notification list with mark-as-read, relative timestamps, and custom items.

NotificationBadge

Unread count badge — hidden when count is 0.

NotificationListener

Headless SSE listener with automatic reconnection.

PushPermissionPrompt

Opt-in prompt for push notifications via VAPID.

Setup Guide

Integration requires three steps: configure dependencies, create API routes, and add UI pages.

1. Configure auth dependencies

// src/lib/server/auth.ts
import { createAuthDeps, createAuthHandle } from '@urbicon-ui/auth/server';
import { createPrismaRepos } from '@urbicon-ui/auth/server/adapters/prisma';
import { createLettermintTransport } from '@urbicon-ui/auth/server/email/lettermint';
import { prisma } from '$lib/server/db';
import { env } from '$env/static/private';

export const authDeps = createAuthDeps({
  config: {
    jwt: { secret: env.JWT_SECRET },
    password: { minLength: 8 },
    lockout: { maxAttempts: 5, durationMs: 15 * 60_000 }
  },
  repos: createPrismaRepos(prisma),
  email: createLettermintTransport({ apiKey: env.EMAIL_API_KEY })
});

2. Add the SvelteKit hook

The handle hook validates sessions, protects routes, adds CSRF and security headers.

// src/hooks.server.ts
import { createAuthHandle } from '@urbicon-ui/auth/server';
import { authDeps } from '$lib/server/auth';

export const handle = createAuthHandle(authDeps, {
  publicRoutes: ['/', '/auth/login', '/auth/register'],
  loginRedirect: '/auth/login'
});

3. Create API route handlers

Each UI component expects a corresponding API endpoint. The handler factories include all validation, hashing, rate limiting, and security.

// Each auth flow needs a SvelteKit API route:
// src/routes/api/auth/login/+server.ts
import { createLoginHandler } from '@urbicon-ui/auth/server';
import { authDeps } from '$lib/server/auth';
export const POST = createLoginHandler(authDeps);

// src/routes/api/auth/register/+server.ts
import { createRegisterHandler } from '@urbicon-ui/auth/server';
export const POST = createRegisterHandler(authDeps);

// src/routes/api/auth/forgot-password/+server.ts
import { createForgotPasswordHandler } from '@urbicon-ui/auth/server';
export const POST = createForgotPasswordHandler(authDeps);

// Same pattern for: reset-password, verify-email, logout, me

4. Add UI pages

Components auto-detect locale from @urbicon-ui/i18n. No t prop needed when the i18n context is set up.

<!-- src/routes/auth/login/+page.svelte -->
<script>
  import { LoginPage } from '@urbicon-ui/auth';
  import { goto } from '$app/navigation';
</script>

<!-- Locale auto-detected from i18n context -->
<LoginPage
  onSuccess={() => goto('/')}
  passkeyApiPath="/api/auth/passkey"
  rememberMe
/>