ideal-auth

library1.2.0jsnpmunverified

Auth primitives for the JS ecosystem — stateless encrypted sessions, password hashing, and two-factor support. Zero framework dependencies; inspired by Laravel's Auth and Hash facades. Current stable version is 1.2.0, released monthly. Key differentiators: uses iron-session for AES-256-CBC + HMAC encrypted cookies, supports two session modes (resolveUser for DB-backed, sessionFields for zero DB calls), built-in TOTP for 2FA, and per-request autoTouch override for frameworks like Next.js. Ships TypeScript types, requires Node >=18, and has optional bcryptjs peer dependency.

auth-security web-framework serialization

npm install ideal-auth

github ↗package ↗

INSTALL

IMPORT

SIG · IDEAL-AUTH

ideal-auth

auth-securityjavascriptv1.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

createAuth

✓ import { createAuth } from 'ideal-auth'

✗ import createAuth from 'ideal-auth'

Default export not available; named export only.

createHash

✓ import { createHash } from 'ideal-auth'

Named export; bcryptjs must be installed as peer dependency if used.

prehash

✓ import { prehash } from 'ideal-auth'

Utility function for consistent string normalization before hashing.

Shows setup with createAuth and createHash, cookie bridge for Next.js, and basic login/check/logout flow.

import { createAuth, createHash } from 'ideal-auth'; import { cookies } from 'next/headers'; import { db } from '@/lib/db'; const hash = createHash({ rounds: 12 }); export const auth = createAuth({ secret: process.env.IDEAL_AUTH_SECRET ?? '', cookie: { get: async (name) => (await cookies()).get(name)?.value, set: async (name, value, opts) => (await cookies()).set(name, value, opts), delete: async (name) => (await cookies()).delete(name), }, hash, resolveUser: async (id) => db.user.findUnique({ where: { id } }), resolveUserByCredentials: async (creds) => db.user.findUnique({ where: { email: creds.email } }), }); // In a server action: const session = auth(); await session.attempt({ email: 'user@example.com', password: 's3cret' }); const user = await session.user(); await session.logout();

Debug

Known issues

breakingv1.0.0: createAuth now requires a single type parameter TUser; removed previous dual-generic signature.

fix

Update to createAuth<SessionUser>({ ... }) — remove the second type argument.

affects: >=1.0.0

breakingv0.7.0: Simplified type system — createAuth takes only TUser, not TFields.

fix

Migrate to single generic: createAuth<SessionUser>({ ... }).

affects: >=0.7.0 <1.0.0

deprecatedv0.5.0: Session secret environment variable renamed from IDEAL_AUTH_SESSION_SECRET to IDEAL_AUTH_SECRET.

fix

Rename environment variable to IDEAL_AUTH_SECRET.

affects: >=0.5.0

gotchaPer-request autoTouch override is only available in v1.2.0+; earlier versions ignore per-request options.

fix

Upgrade to v1.2.0 or later to use auth({ autoTouch: true }).

affects: <1.2.0

gotchabcryptjs is optional but createHash() fails at runtime if not installed; no clear error message.

fix

Install bcryptjs as a dependency if using createHash() or provide a custom HashInstance.

affects: >=0.4.0

gotchasessionFields must be declared with 'as const' to get narrow types; otherwise user() returns generic type.

fix

Use 'as const' when defining sessionFields array.

affects: >=0.6.0

gotchasecret must be at least 32 characters; shorter values throw an error at runtime.

fix

Generate a 32+ character secret via 'bunx ideal-auth secret'.

affects: >=0.1.0

Errors

Common errors & fixes

Error: Secret must be at least 32 characters long

IDEAL_AUTH_SECRET is too short in environment variables.

fix

Generate a 32+ character secret: bunx ideal-auth secret, then add to .env.

Cannot find module 'bcryptjs'

bcryptjs not installed but createHash() is used.

fix

Run: npm install bcryptjs or provide a custom HashInstance.

Type 'undefined' is not assignable to type 'string'

sessionFields array not declared with 'as const' causing TypeScript to infer string[].

fix

Add 'as const' to the sessionFields array: const sessionFields = ['email', 'name'] as const;

Type 'typeof auth' is not a valid async function

Attempting to call auth() without awaiting in an async context incorrectly.

fix

Ensure auth() is called with await: const session = await auth();

Error: iron-session cookie parsing failed

Corrupted session cookie or mismatched secret.

fix

Regenerate IDEAL_AUTH_SECRET and clear all session cookies.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

bcryptjsoptionalOptional peer dependency, required only for createHash() password hashing

typescriptoptionalPeer dependency for type definitions

Agent activity

21 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ramonmalcolm10/ideal-auth ↗

packagehttps://www.npmjs.com/package/ideal-auth ↗