lucia

An open source auth library that abstracts away the complexity of handling sessions. It works alongside your database to provide an API that's easy to use, understand, and extend.

Documentation

Changelog

Installation

npm install lucia
pnpm add lucia
yarn add lucia

lucia

3.2.2

Patch changes

• Fix cookie expiration.

3.2.1

Patch changes

• #1708 by @pilcrowOnPaper : Update dependencies.

3.2.0

Minor changes

• #1548 by @pilcrowOnPaper : Add generateIdFromEntropySize()

Patch changes

• #1546 by @pilcrowOnPaper : Fix options.sessionCookie parameter type in Lucia

• #1548 by @pilcrowOnPaper : Optimize session ID generation

3.1.1

• Fix types.

3.1.0

• Add option to configure user ID type (#1472).

3.0.1

• Fix LegacyScrypt generating malformed hash (see #1370 - no security concerns)

3.0.0

See the migration guide.

2.7.6

Patch changes

• #1309 by @pilcrowOnPaper : Fix setCookie() method in SvelteKit middleware

2.7.5

Patch changes

• #1301 by @matteopolak : Update SvelteKit middleware to be compatible with SvelteKit v2

2.7.4

Patch changes

• #1250 by @pilcrowOnPaper : Revert #1158

• #1256 by @FredTreg : Allow debug message to be displayed when request origin not available

• #1254 by @pilcrowOnPaper : Remove unused svelte field from package.json

• #1250 by @pilcrowOnPaper : Remove nanoid dependency

2.7.3

Patch changes

• #1217 by @pilcrowOnPaper : Fix express() middleware setting incorrect Max-Age cookie attribute

• #1158 by @pilcrowOnPaper : Update dependencies

2.7.2

Patch changes

• #1212 by @pilcrowOnPaper : Remove dev dependencies for typing

2.7.1

Patch changes

• #1171 by @pilcrowOnPaper : Add proper attributes for @noble/hashes

2.7.0

Minor changes

• #1081 by @SkepticMystic : Add experimental joinAdapters()

• #1148 by @pilcrowOnPaper : Add AuthRequest.invalidate()

Patch changes

• #1134 by @giacomoferretti : Fix unhandled rejection error when using AuthRequest.validate() and AuthRequest.validateBearerToken()

• #1144 by @MrNiceRicee : Update elysia() middleware types

2.6.0

Minor changes

• #1113 by @pilcrowOnPaper : Add options.responseMode params to apple()

• #1100 by @pilcrowOnPaper : Add nextjs_future() middleware

• #1099 by @pilcrowOnPaper : Mark Auth.validateRequestOrigin() as deprecated

• #1099 by @pilcrowOnPaper : Replace type RequestContext with MiddlewareRequestContext for type Middleware

Patch changes

• #1105 by @pilcrowOnPaper : Fix Auth.useKey() accepting any password if the key password was set to null

• #1105 by @pilcrowOnPaper : Fix Auth.createUser() setting key password to null if key.password was an empty string

2.5.0

Minor changes

• #992 by @Tirke : Add elysia() middleware

Patch changes

• #1079 by @pilcrowOnPaper : Fix Auth.handleRequest() causing error in middleware when nextjs() was used

2.4.2

Patch changes

• #1046 by @pilcrowOnPaper : Fix AuthRequest.validateBearerToken() returning null when session is idle

2.4.1

Patch changes

• #1041 by @pilcrowOnPaper : Support Astro v3

2.4.0

Minor changes

• #986 by @KazuumiN : Fixed updateKeyPassword() to return a Promise<Key>

Patch changes

• #980 by @pilcrowOnPaper : Remove unused and undocumented csrfProtection.baseDomain configuration

• #985 by @pilcrowOnPaper : Fix Lucia throwing AUTH_OUTDATED_PASSWORD when using Bcrypt

2.3.0

Minor changes

• #958 by @aust1nz : Add fastify() middleware

2.2.0

Minor changes

• #944 by @pilcrowOnPaper : Add hono() middleware

2.1.0

Minor changes

• #911 by @pilcrowOnPaper : Allow null in csrfProtection.allowedSubdomains configuration array

2.0.0

Major changes

• #884 by @pilcrowOnPaper : Update version

2.0.0-beta.7

Major changes

• #866 by @pilcrowOnPaper : Rename cookieName to sessionCookieName in Middleware

Minor changes

• #864 by @pilcrowOnPaper : Export generateLuciaPasswordHash, validateLuciaPasswordHash from /utils

Patch changes

• #849 by @pilcrowOnPaper : Remove Node dependent type check

• #848 by @pilcrowOnPaper : Normalize string before comparing when validating hashes

2.0.0-beta.6

Major changes

• #836 by @pilcrowOnPaper : User ids and session ids only consist of lowercase letters and numbers by default

• #839 by @pilcrowOnPaper : AuthRequest.validate() and Auth.validateBearerToken() throws database errors

Minor changes

• #838 by @pilcrowOnPaper : Add Auth.transformDatabaseUser(), Auth.transformDatabaseKey(), and Auth.transformDatabaseSession()

• #838 by @pilcrowOnPaper : Export createKeyId()

2.0.0-beta.5

Major changes

• #812 by @pilcrowOnPaper : Remove allowedRequestOrigins configuration

Patch changes

• #815 by @pilcrowOnPaper : Fix getSessionAndUser() adapter method getting called when using session adapters

2.0.0-beta.4

Patch changes

• #799 by @ernestoresende : fix nextjs middleware runtime errors on app router

• #801 by @pilcrowOnPaper : Fix express() middleware returning broken request url

2.0.0-beta.3

Major changes

• #773 by @pilcrowOnPaper : Update web() middleware

• #772 by @pilcrowOnPaper : Update Auth.createSession() params

• #772 by @pilcrowOnPaper : Update Auth.createKey() params

• #773 by @pilcrowOnPaper : Remove AuthRequest.renewBearerToken()

• #773 by @pilcrowOnPaper : Update nextjs() middleware

• #773 by @pilcrowOnPaper : Overhaul session renewal

  • Remove Auth.renewSession()

  • Add sessionCookie.expires configuration

• #772 by @pilcrowOnPaper : Remove generateUserId() configuration

• #772 by @pilcrowOnPaper : Add optional userId to Auth.createUser() params

2.0.0-beta.2

Major changes

• #739 by @pilcrowOnPaper : Auth.readSessionCookie() and Auth.readBearerToken() takes the session and authorization header value respectively

• #754 by @pilcrowOnPaper : Auth.validateRequestOrigin() checks for CSRF regardless of csrfProtection config

• #753 by @pilcrowOnPaper : Rename requestOrigins config to allowedRequestOrigins

Minor changes

• #739 by @pilcrowOnPaper : Add AuthRequest.renewBearerToken()

• #752 by @pilcrowOnPaper : Export parseCookie() from /utils

2.0.0-beta.1

Patch changes

• #735 by @pilcrowOnPaper : Fix Session.fresh fixed to false

2.0.0-beta.0

Major changes

• #682 by @pilcrowOnPaper : Update configuration

  • Remove autoDatabaseCleanup

  • Remove transformDatabaseUser() (see transformUserAttributes())

  • Replace generateCustomUserId() with generateUserId()

  • Replace hash with passwordHash

  • Replace origin with requestOrigins

  • Replace sessionCookie with sessionCookie.attributes

  • Add sessionCookie.name for setting session cookie name

  • Add transformUserAttributes() for defining user attributes (userId is automatically included)

  • Add transformSessionAttributes() for defining session attributes

• #682 by @pilcrowOnPaper : Update Auth methods:

  • Remove getSessionUser()

  • Remove validateSessionUser()

  • Remove parseRequestHeaders()

  • Add readSessionCookie()

  • Add validateRequestOrigin()

• #682 by @pilcrowOnPaper : Remove primary keys

  • Remove Key.primary

  • Rename Auth.createUser() params options.primaryKey to options.key

  • Remove column key(primary_key)

• #682 by @pilcrowOnPaper : Remove single use keys

  • Lucia v2 no longer supports @lucia-auth/tokens

  • Remove Session.type

  • Update Auth.createKey() params

  • Remove column key(expires)

• #682 by @pilcrowOnPaper : Update Session

  • Remove Session.userId

  • Add Session.user

• #682 by @pilcrowOnPaper : Remove AuthRequest.validateUser()

• #682 by @pilcrowOnPaper : Introduce custom session attributes

  • Update Auth.createSession() params

  • Update behavior of Auth.renewSession() to include attributes of old session to renewed session automatically

• #682 by @pilcrowOnPaper : Overhaul adapter API

  • Remove UserAdapter.updateUserAttributes()

  • Remove UserAdapter.deleteNonPrimaryKey()

  • Remove UserAdapter.updateKeyPassword()

  • Remove Adapter?.getSessionAndUserBySessionId()

  • Update UserAdapter.setUser() params

  • Remove UserAdapter.getKey() params shouldDataBeDeleted()

  • Add UserAdapter.updateUser()

  • Add UserAdapter.deleteKey()

  • Add UserAdapter.updateKey()

  • Add SessionAdapter.updateSession()

  • Add Adapter.getSessionAndUser()

  • Rename type AdapterFunction to InitializeAdapter

• #682 by @pilcrowOnPaper : Update adapter specifications

  • Insert and update methods do not return anything

  • Insert and update methods for sessions and keys may optionally throw a Lucia error on invalid user id

  • Insert methods do not throw Lucia errors on duplicate session and user ids

• #682 by @pilcrowOnPaper : Remove errors:

  • AUTH_DUPLICATE_SESSION_ID

  • AUTO_USER_ID_GENERATION_NOT_SUPPORTED

  • AUTH_EXPIRED_KEY

• #682 by @pilcrowOnPaper : Remove auto database clean up functionality

• #682 by @pilcrowOnPaper : Update Middleware takes a new Context params

• #682 by @pilcrowOnPaper : Update exports:

  • Replace default export with named lucia()

  • Removed generateRandomString()

  • Removed serializeCookie()

  • Removed Cookie

• #682 by @pilcrowOnPaper : Rename SESSION_COOKIE_NAME to DEFAULT_SESSION_COOKIE_NAME

• #682 by @pilcrowOnPaper : NPM package lucia-auth is renamed to lucia

• #682 by @pilcrowOnPaper : Update RequestContext:

  • Add RequestContext.headers.authorization

  • Add optional RequestContext.storedSessionCookie

Minor changes

• #682 by @pilcrowOnPaper : Support bearer tokens

  • Add Auth.readBearerToken()

  • Add AuthRequest.validateBearerToken()

• #682 by @pilcrowOnPaper : New lucia/utils export:

  • generateRandomString()

  • serializeCookie()

  • isWithinExpiration()