Package Exports

@kitiumai/auth
@kitiumai/auth/dist/index.js
@kitiumai/auth/dist/index.mjs

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@kitiumai/auth) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

@kitium/auth (Kitium Auth Core)

Complete authentication core for Node/TypeScript apps. Provides:

OAuth flows (Google, GitHub, Microsoft, Discord, generic OIDC)
API keys: issue, verify, revoke with caching
Sessions: create, refresh, delete, signed JWT tokens
Extensible storage, cache, and billing interfaces

Install

npm install @kitium/auth

Quick Start

import { AuthCore } from '@kitium/auth'
import type { StorageAdapter, CacheAdapter, BillingAdapter, AuthProvider } from '@kitium/auth'

// 1) Provide adapters (in memory, Postgres, Redis, Stripe shown in other packages)
const storage: StorageAdapter = /* your StorageAdapter implementation */
const cache: CacheAdapter | undefined = /* optional */
const billing: BillingAdapter | undefined = /* optional */

// 2) Create AuthCore
const auth = new AuthCore(storage, {
  jwtSecret: process.env.JWT_SECRET!,
  cache,
  billing,
  providers: [
    { id: 'google', type: 'oauth', clientId: process.env.GOOGLE_ID!, clientSecret: process.env.GOOGLE_SECRET! }
  ] as AuthProvider[]
})

await auth.initialize()

OAuth Authorization URL

const { url, state, codeVerifier } = auth.getOAuthAuthorizationUrl(
  'google',
  'https://your.app/api/auth/callback/google'
)
// redirect user to `url`

OAuth Callback

// After user returns from provider
const result = await auth.handleOAuthCallback('google', code, state, codeVerifier)
// result = { userId, session, profile, tokens }

API Keys

// Issue
const issued = await auth.issueApiKey({ principalId: 'user_123', scopes: ['api.read'] })
// { id, key, prefix, lastFour, createdAt, expiresAt }

// Verify
try {
  const verification = await auth.verifyApiKey('kit_abcdef...')
  // { valid, principalId, scopes, plan, orgId, keyId, expiresAt, rateLimit }
} catch (e) {
  // handle invalid/expired/not found
}

// Revoke
await auth.revokeApiKey(issued.id)

Sessions

const session = await auth.createSession('user_123')
const token = await auth.generateSessionToken(session.id)

// Get/refresh/delete
const current = await auth.getSession(session.id)
const refreshed = await auth.refreshSession(session.id)
await auth.deleteSession(session.id)

Users and Organizations

// Users
const user = await auth.createUser({ email: 'a@b.com', name: 'Alice' })
await auth.updateUser(user.id, { plan: 'pro' })
await auth.deleteUser(user.id)

// Plans
await auth.addPlan({ id: 'pro', entitlements: ['api.read', 'api.write'] })
const plan = await auth.getPlan('pro')

// Orgs
const org = await auth.createOrganization({ name: 'ACME', plan: 'pro', ownerId: 'user_123' })
const orgData = await auth.getOrganization(org.id)

Using with Adapters

Storage: use @kitium/auth-postgres (Postgres) or the in-memory adapter in this package for testing.
Cache: use @kitium/auth-redis for Redis-backed caching.
Billing: use @kitium/auth-stripe for Stripe subscriptions/billing.

Error Handling

All methods throw rich errors (e.g., ValidationError, ApiKeyError, SessionError). Catch and map to HTTP responses as needed.

TypeScript

The package is fully typed. Import types from @kitium/auth.

License

MIT