@authcore/core

Framework-agnostic authentication engine. Types, validation, password hashing, JWT, and adapter interfaces.

This is the core package that powers all AuthCore framework adapters. You typically won't use it directly. Use @authcore/express or @authcore/fastify instead.

Install

npm install @authcore/core

What's Inside

createAuth(config)

The main factory that creates an auth instance with register, login, verifyToken, verifyEmail, forgotPassword, resetPassword, invite, and acceptInvitation methods.

import { createAuth } from '@authcore/core'

const auth = createAuth({
  db: myDatabaseAdapter,
  session: { strategy: 'jwt', secret: 'your-secret', expiresIn: '7d' },
  email: { provider: myEmailAdapter, from: '[email protected]' },
  features: ['emailVerification', 'passwordReset', 'invitation'],
  password: { minLength: 8 },
  rbac: { defaultRole: 'user' },
  callbacks: {
    onSignUp: (user) => { /* ... */ },
    onSignIn: (user) => { /* ... */ },
  },
})

const { user, token } = await auth.register({ email: '[email protected]', password: 'securepass' })
const { user, token } = await auth.login({ email: '[email protected]', password: 'securepass' })
const publicUser = await auth.verifyToken(token)

Adapter Interfaces

Implement these to add support for any database or email provider:

import type { DatabaseAdapter, EmailAdapter } from '@authcore/core'

DatabaseAdapter:

interface DatabaseAdapter {
  findUserByEmail(email: string): Promise<User | null>
  findUserById(id: string): Promise<User | null>
  createUser(data: CreateUserInput): Promise<User>
  updateUser(id: string, data: Partial<User>): Promise<User>
  createToken(data: CreateTokenInput): Promise<Token>
  findToken(rawToken: string, type: TokenType): Promise<Token | null>
  deleteToken(id: string): Promise<void>
  deleteExpiredTokens(): Promise<void>
}

EmailAdapter:

interface EmailAdapter {
  send(options: { from: string; to: string; subject: string; html: string; text: string }): Promise<void>
}

Types

import type {
  User,
  PublicUser,
  Token,
  TokenType,
  AuthCoreConfig,
  AuthCore,
  DatabaseAdapter,
  EmailAdapter,
  AuthError,
} from '@authcore/core'

Utilities

import {
  hashPassword,
  verifyPassword,
  generateOpaqueToken,
  hashToken,
  safeCompareTokens,
  signJwt,
  verifyJwt,
} from '@authcore/core'

Validation Schemas (Zod)

import {
  registerSchema,
  loginSchema,
  forgotPasswordSchema,
  resetPasswordSchema,
  verifyEmailSchema,
  inviteSchema,
  acceptInvitationSchema,
} from '@authcore/core'

RBAC

Users have a role field (string). The default role for new registrations is 'user', configurable via rbac.defaultRole. The role is included in the JWT payload, so role checks don't need extra database lookups.

Invitation

Enable the 'invitation' feature to let authenticated users invite new users by email. The invited user receives a link to set their password and activate their account. Invitation tokens expire in 48 hours.

License

MIT