@geenius/auth

Authentication contracts, provider adapters, UI bindings, and Convex support for the Geenius ecosystem.

@geenius/auth publishes a shared auth contract plus the launch UI variants and DB providers defined in variants.json, so apps can adopt a consistent authentication surface without relying on unpublished internals.

Install

pnpm add @geenius/auth

Import Paths

Use the root package for the framework-agnostic contract, then opt into the subpath that matches your UI or backend runtime.

import {
  configureAuth,
  createAuthProvider,
  createAuthRateLimiter,
  createCsrfToken,
  getSafeRelativeRedirect,
  validateAuthCookieOptions,
} from '@geenius/auth'
import { AuthProvider, SignInPage } from '@geenius/auth/react'
import { SignInPage as ReactCssSignInPage } from '@geenius/auth/react-css'
import '@geenius/auth/react-css/styles.css'
import { createAuth, SignInPage as SolidSignInPage } from '@geenius/auth/solidjs'
import { SignInPage as SolidCssSignInPage } from '@geenius/auth/solidjs-css'
import '@geenius/auth/solidjs-css/styles.css'
import { authTables } from '@geenius/auth/convex'
import { createMemoryAuthStore } from '@geenius/auth/memory'

| Import path | Purpose | | --- | --- | | @geenius/auth | Root shared contract, configuration helpers, @geenius/adapters auth interop types, and @geenius/db adapter contract types | | @geenius/auth/config | Tree-shakable configuration helpers mirrored from the shared contract | | @geenius/auth/react | React hooks, providers, and Tailwind-styled components/pages | | @geenius/auth/react-css | React hooks, providers, and vanilla CSS components/pages | | @geenius/auth/react-css/styles.css | Stylesheet for the React CSS variant | | @geenius/auth/solidjs | SolidJS primitives, providers, and Tailwind-styled components/pages | | @geenius/auth/solidjs-css | SolidJS primitives, providers, and vanilla CSS components/pages | | @geenius/auth/solidjs-css/styles.css | Stylesheet for the SolidJS CSS variant | | @geenius/auth/convex | Auth schema tables and Convex server helpers | | @geenius/auth/neon | Neon/Postgres auth migration helpers | | @geenius/auth/cloudflareKV | Cloudflare KV auth store helpers | | @geenius/auth/memory | In-memory auth store for tests and local dev |

The active launch support matrix is react, react-css, solidjs, and solidjs-css, plus the four DB provider subpaths above. Legacy library-variant export keys may still exist for compatibility, but they are marked inScope:false in variants.json and are excluded from build, lint, test, Storybook, coverage, and packed-smoke sweeps unless OMEGA_INCLUDE_OUT_OF_SCOPE=1 is set for a planned re-inclusion.

The public DB provider key is cloudflareKV. Private workspace package names may use npm-safe lowercase spelling such as @geenius/auth-cloudflare-kv, but consumer imports, docs, and variants.json use the camel-case subpath.

Better Auth, Convex Auth, Clerk, and Supabase Auth are auth-provider adapters behind the shared contract. Supabase and MongoDB database providers are post-launch DB-axis additions, not V1 package imports.

Usage

import { configureAuth, getSafeRelativeRedirect } from '@geenius/auth'
import { AuthProvider, SignInPage } from '@geenius/auth/react'

configureAuth({
  provider: 'better-auth',
  baseUrl: '/api/auth',
})

const safeRedirect = getSafeRelativeRedirect('/app?welcome=1')

export function AuthScreen() {
  return (
    <AuthProvider provider="better-auth" config={{ baseUrl: '/api/auth' }}>
      <SignInPage branding={{ name: 'Geenius Cloud' }} />
    </AuthProvider>
  )
}

import {
  createAuthRateLimiter,
  createCsrfToken,
  DEFAULT_CSRF_HEADER_NAME,
  resolveAuthCookieOptions,
  validateAuthCookieOptions,
} from '@geenius/auth'

const csrfToken = createCsrfToken()
const limiter = createAuthRateLimiter({ windowMs: 60_000, max: 5 })
const cookieOptions = resolveAuthCookieOptions({ maxAge: 60 * 60 * 24 * 7 })
const cookieValidation = validateAuthCookieOptions(cookieOptions)

if (!limiter.check('sign-in:[email protected]').allowed) {
  throw new Error('Too many sign-in attempts')
}

response.headers.set(DEFAULT_CSRF_HEADER_NAME, csrfToken)

if (!cookieValidation.valid) {
  throw new Error(cookieValidation.issues[0]?.message)
}

import '@geenius/auth/react-css/styles.css'
import { AuthProvider, SignInPage } from '@geenius/auth/react-css'

export function MarketingSignIn() {
  return (
    <AuthProvider provider="better-auth" config={{ baseUrl: '/api/auth' }}>
      <SignInPage branding={{ name: 'Geenius Cloud', tagline: 'Sign in to continue.' }} />
    </AuthProvider>
  )
}

import { AuthProvider, SignInPage } from '@geenius/auth/solidjs'

export function SolidAuthRoute() {
  return (
    <AuthProvider provider="better-auth" config={{ baseUrl: '/api/auth' }}>
      <SignInPage branding={{ name: 'Geenius Cloud' }} />
    </AuthProvider>
  )
}

import { authTables } from '@geenius/auth/convex'

export const schema = authTables

import { createMemoryAuthStore } from '@geenius/auth/memory'

const store = createMemoryAuthStore({
  users: [
    {
      id: 'user_1',
      email: '[email protected]',
      displayName: 'Operator One',
      avatarUrl: null,
      role: 'admin',
      permissions: ['workspace:read'],
      emailVerified: true,
      mfaEnabled: false,
      createdAt: new Date(),
      updatedAt: new Date(),
      lastLoginAt: new Date(),
    },
  ],
})

const firstPage = await store.listUsers({ limit: 20 })
const nextPage = firstPage.nextCursor
  ? await store.listUsers({ cursor: firstPage.nextCursor, limit: 20 })
  : { items: [], nextCursor: null }
const admins = await store.listUsers({ filter: { role: 'admin' }, limit: 20 })

Review Apps

The repository includes one stock Storybook v10 app per UI variant under apps/storybook-<variant>/. Each app consumes the shared @geenius/storybook preset and keeps provider/theme wiring isolated per variant.

Contributing Tests

variants.json is the only place to add or change auth variants. Scripts, Playwright projects, size budgets, Storybook parity checks, and package filters read that manifest through @geenius/release-toolkit; shared package metadata lives in the top-level shared field.

Useful gates:

• pnpm test:gauntlet runs the PR-blocking lint, type, unit, package, size, audit, and license gates.
• pnpm test:all adds Storybook, DB conformance/migration, Playwright, accessibility, visual, performance, and coverage gates.
• pnpm test:visual -- --update-snapshots updates visual baselines after intentional UI changes.
• pnpm test:mutation runs the nightly Stryker mutation suite for pure logic.

When adding or re-including a variant, create or update its packages/<variant> source, register it in variants.json, remove inScope:false, and let the manifest-driven tests expose missing exports, Storybook coverage, e2e coverage, size limits, and packed-smoke coverage.

Run pnpm test:visual -- --update-snapshots only after an intentional visual change, then review the updated screenshots before committing them.

Package Contract

• Root imports expose the shared, framework-agnostic auth contract.
• Root type exports include AuthContractAdapter, AuthContractIdentity, AuthContractSession, and AuthContractHealth for low-level bridges that need the SDK-free @geenius/adapters auth contract.
• Root type exports include AuthDbAdapter, AuthDbListOptions, AuthDbQueryFilter, and launch-provider option aliases for host-owned persistence from @geenius/db.
• Root utilities include redirect normalization through getSafeRelativeRedirect for route guards and auth callback handling.
• Root utilities include CSRF token creation/verification, secure cookie option validation (httpOnly, secure, sameSite=lax), and an in-memory rate-limit primitive for custom auth endpoints.
• Convex Auth adapters accept app-owned convexOperations for session management, MFA, and password-change flows so custom Convex queries/mutations can satisfy the shared provider contract.
• React and SolidJS consumers use stable subpath exports for Tailwind and vanilla CSS variants.
• Review apps stay out of the publish surface.
• Versioning and release are handled through Changesets and GitHub Actions.

License

FSL-1.1-Apache-2.0. Commercial use is governed by the terms in LICENSE.