ideal-auth 0.3.0 → 0.5.0

package/README.md

@@ -12,17 +12,19 @@ Provide a cookie bridge (3 functions) once during setup, and `auth().login(user)
 bun add ideal-auth
 ```
 
-## Generate Secret
+## Generate Secrets
 
 ```bash
+# Session secret (required — used by createAuth)
 bunx ideal-auth secret
-```
+# IDEAL_AUTH_SECRET=aLThikMgJKMBB5WZLE-lCaOQUdgPWU8BHRv99bkYaVY
 
-```
-IDEAL_AUTH_SECRET=aLThikMgJKMBB5WZLE-lCaOQUdgPWU8BHRv99bkYaVY
+# Encryption key (optional — used by encrypt/decrypt for data at rest)
+bunx ideal-auth encryption-key
+# ENCRYPTION_KEY=9546dd9fa461ce15f0aacd6e1b461b52
 ```
 
-Copy the output into your `.env` file. The secret must be at least 32 characters.
+Copy the output into your `.env` file. `IDEAL_AUTH_SECRET` must be at least 32 characters. `ENCRYPTION_KEY` is only needed if you use `encrypt()`/`decrypt()` (e.g., encrypting TOTP secrets or access tokens at rest).
 
 ## Quick Start
 
@@ -94,12 +96,13 @@ Returns a function `auth()` that creates an `AuthInstance` on each call.
 | --- | --- | --- | --- |
 | `secret` | `string` | Yes | — |
 | `cookie` | `CookieBridge` | Yes | — |
-| `resolveUser` | `(id: string) => Promise<User \| null>` | Yes | — |
+| `resolveUser` | `(id: string) => Promise<User \| null \| undefined>` | Yes (unless `sessionFields` is provided) | — |
+| `sessionFields` | `(keyof User & string)[]` | Yes (unless `resolveUser` is provided) | — |
 | `hash` | `HashInstance` | No | — |
-| `resolveUserByCredentials` | `(creds: Record<string, any>) => Promise<User \| null>` | No | — |
+| `resolveUserByCredentials` | `(creds: Record<string, any>) => Promise<User \| null \| undefined>` | No | — |
 | `credentialKey` | `string` | No | `'password'` |
 | `passwordField` | `string` | No | `'password'` |
-| `attemptUser` | `(creds: Record<string, any>) => Promise<User \| null>` | No | — |
+| `attemptUser` | `(creds: Record<string, any>) => Promise<User \| null \| undefined>` | No | — |
 | `session.cookieName` | `string` | No | `'ideal_session'` |
 | `session.maxAge` | `number` (seconds) | No | `604800` (7 days) |
 | `session.rememberMaxAge` | `number` (seconds) | No | `2592000` (30 days) |
@@ -171,7 +174,11 @@ const auth = createAuth({
 
 ### `createHash(config?)`
 
-Returns a `HashInstance` using bcrypt.
+Returns a `HashInstance` using bcrypt. Requires `bcryptjs` (optional peer dependency):
+
+```bash
+bun add bcryptjs
+```
 
 | Option | Type | Default |
 | --- | --- | --- |
@@ -186,6 +193,27 @@ const hashed = await hash.make('password');
 const valid  = await hash.verify('password', hashed); // true
 ```
 
+### Custom hash (bring your own)
+
+Skip `bcryptjs` entirely by providing your own `HashInstance`:
+
+```typescript
+import { prehash } from 'ideal-auth';
+import type { HashInstance } from 'ideal-auth';
+
+// Bun native bcrypt (use prehash to prevent silent truncation at 72 bytes)
+const hash: HashInstance = {
+  make: (password) => Bun.password.hash(prehash(password), { algorithm: 'bcrypt', cost: 12 }),
+  verify: (password, hash) => Bun.password.verify(prehash(password), hash),
+};
+
+// Bun argon2id (OWASP recommended — no prehash needed, no input length limit)
+const hash: HashInstance = {
+  make: (password) => Bun.password.hash(password, { algorithm: 'argon2id' }),
+  verify: (password, hash) => Bun.password.verify(password, hash),
+};
+```
+
 ---
 
 ### Crypto Utilities
@@ -517,10 +545,10 @@ cookie: {
 
 ## Dependencies
 
-| Package | Purpose |
-| --- | --- |
-| `iron-session` | Session sealing/unsealing (AES-256-CBC + HMAC) |
-| `bcryptjs` | Password hashing |
+| Package | Purpose | Required |
+| --- | --- | --- |
+| `iron-session` | Session sealing/unsealing (AES-256-CBC + HMAC) | Yes |
+| `bcryptjs` | Password hashing (used by `createHash()`) | Optional — not needed if you provide your own `HashInstance` |
 
 Zero framework imports. Works in Node, Bun, Deno, and edge runtimes.
 

package/dist/auth-instance.d.ts

@@ -6,13 +6,13 @@ interface AuthInstanceDeps<TUser extends AnyUser> {
     maxAge: number;
     rememberMaxAge: number;
     cookieOptions: ConfigurableCookieOptions;
-    resolveUser?: (id: string) => Promise<TUser | null>;
+    resolveUser?: (id: string) => Promise<TUser | null | undefined>;
     sessionFields?: (keyof TUser & string)[];
     hash?: HashInstance;
-    resolveUserByCredentials?: (credentials: Record<string, any>) => Promise<TUser | null>;
+    resolveUserByCredentials?: (credentials: Record<string, any>) => Promise<TUser | null | undefined>;
     credentialKey: string;
     passwordField: string;
-    attemptUser?: (credentials: Record<string, any>) => Promise<TUser | null>;
+    attemptUser?: (credentials: Record<string, any>) => Promise<TUser | null | undefined>;
 }
 export declare function createAuthInstance<TUser extends AnyUser>(deps: AuthInstanceDeps<TUser>): AuthInstance<TUser>;
 export {};

package/dist/auth-instance.js

@@ -106,7 +106,7 @@ export function createAuthInstance(deps) {
             }
             // Database-backed: resolve user via callback
             if (deps.resolveUser) {
-                cachedUser = await deps.resolveUser(session.uid);
+                cachedUser = (await deps.resolveUser(session.uid)) ?? null;
                 return cachedUser;
             }
             cachedUser = null;

package/dist/hash/index.d.ts

@@ -1,2 +1,12 @@
 import type { HashInstance, HashConfig } from '../types';
+/**
+ * SHA-256 prehash for bcrypt's 72-byte input limit.
+ * Passwords exceeding 72 UTF-8 bytes are hashed to a 44-char base64 string
+ * before being passed to bcrypt, preventing silent truncation.
+ *
+ * Only needed for bcrypt — argon2 has no input length limit.
+ * Applied automatically by `createHash()`. Use this when building
+ * a custom bcrypt `HashInstance` (e.g., with `Bun.password`).
+ */
+export declare function prehash(password: string): string;
 export declare function createHash(config?: HashConfig): HashInstance;

package/dist/hash/index.js

@@ -1,23 +1,49 @@
 import { createHash as nodeCryptoHash } from 'node:crypto';
-import bcrypt from 'bcryptjs';
 const DEFAULT_ROUNDS = 12;
 const BCRYPT_MAX_BYTES = 72;
-function prehash(password) {
+/**
+ * SHA-256 prehash for bcrypt's 72-byte input limit.
+ * Passwords exceeding 72 UTF-8 bytes are hashed to a 44-char base64 string
+ * before being passed to bcrypt, preventing silent truncation.
+ *
+ * Only needed for bcrypt — argon2 has no input length limit.
+ * Applied automatically by `createHash()`. Use this when building
+ * a custom bcrypt `HashInstance` (e.g., with `Bun.password`).
+ */
+export function prehash(password) {
+    if (Buffer.byteLength(password, 'utf8') <= BCRYPT_MAX_BYTES)
+        return password;
     return nodeCryptoHash('sha256').update(password).digest('base64');
 }
+async function loadBcrypt() {
+    try {
+        return await import('bcryptjs');
+    }
+    catch {
+        throw new Error('bcryptjs is required for createHash(). Install it as a dependency in your project.\n' +
+            'Alternatively, provide your own HashInstance (e.g., using Bun.password or argon2).');
+    }
+}
 export function createHash(config) {
     const rounds = config?.rounds ?? DEFAULT_ROUNDS;
+    let bcryptModule = null;
+    async function getBcrypt() {
+        if (!bcryptModule) {
+            bcryptModule = await loadBcrypt();
+        }
+        return bcryptModule;
+    }
     return {
         async make(password) {
             if (!password)
                 throw new Error('password must not be empty');
-            const input = Buffer.byteLength(password, 'utf8') > BCRYPT_MAX_BYTES ? prehash(password) : password;
+            const bcrypt = await getBcrypt();
             const salt = await bcrypt.genSalt(rounds);
-            return bcrypt.hash(input, salt);
+            return bcrypt.hash(prehash(password), salt);
         },
         async verify(password, hash) {
-            const input = Buffer.byteLength(password, 'utf8') > BCRYPT_MAX_BYTES ? prehash(password) : password;
-            return bcrypt.compare(input, hash);
+            const bcrypt = await getBcrypt();
+            return bcrypt.compare(prehash(password), hash);
         },
     };
 }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { createAuth } from './auth';
-export { createHash } from './hash';
+export { createHash, prehash } from './hash';
 export { generateToken } from './crypto/token';
 export { signData, verifySignature } from './crypto/hmac';
 export { encrypt, decrypt } from './crypto/encryption';

package/dist/index.js

@@ -1,7 +1,7 @@
 // Auth
 export { createAuth } from './auth';
 // Hash
-export { createHash } from './hash';
+export { createHash, prehash } from './hash';
 // Crypto utilities
 export { generateToken } from './crypto/token';
 export { signData, verifySignature } from './crypto/hmac';

package/dist/types.d.ts

@@ -27,7 +27,7 @@ export interface SessionPayload {
 export interface LoginOptions {
     remember?: boolean;
 }
-export interface AuthConfig<TUser extends AnyUser = AnyUser> {
+interface AuthConfigBase<TUser extends AnyUser> {
     secret: string;
     cookie: CookieBridge;
     session?: {
@@ -36,33 +36,39 @@ export interface AuthConfig<TUser extends AnyUser = AnyUser> {
         rememberMaxAge?: number;
         cookie?: Partial<ConfigurableCookieOptions>;
     };
-    resolveUser?: (id: string) => Promise<TUser | null>;
-    /**
-     * Fields from the user object to store in the session cookie.
-     * When provided, `resolveUser` is not needed — `user()` returns
-     * the stored fields directly from the cookie.
-     *
-     * The `id` field is always stored. List only additional fields.
-     * Keep the total small — session cookies have a ~4KB size limit.
-     *
-     * Cannot be used together with `resolveUser`.
-     *
-     * **Staleness:** Data is snapshotted at login time. If a user's role
-     * or permissions change server-side, the cookie retains the old values
-     * until the user re-logs in. For authorization-critical fields (role,
-     * permissions, subscription tier), prefer `resolveUser` to get fresh
-     * data on every request.
-     *
-     * **ID type:** `user()` always returns `id` as a `string` on subsequent
-     * requests (read from cookie), even if the original `TUser.id` was a number.
-     */
-    sessionFields?: (keyof TUser & string)[];
     hash?: HashInstance;
-    resolveUserByCredentials?: (credentials: Record<string, any>) => Promise<TUser | null>;
+    resolveUserByCredentials?: (credentials: Record<string, any>) => Promise<TUser | null | undefined>;
     credentialKey?: string;
     passwordField?: string;
-    attemptUser?: (credentials: Record<string, any>) => Promise<TUser | null>;
-}
+    attemptUser?: (credentials: Record<string, any>) => Promise<TUser | null | undefined>;
+}
+/** Database-backed: `user()` calls `resolveUser(id)` on every request. */
+interface AuthConfigWithResolveUser<TUser extends AnyUser> extends AuthConfigBase<TUser> {
+    resolveUser: (id: string) => Promise<TUser | null | undefined>;
+    /** Cannot use `sessionFields` together with `resolveUser`. */
+    sessionFields?: never;
+}
+/**
+ * Cookie-backed: `user()` reads declared fields from the session cookie.
+ *
+ * The `id` field is always stored. List only additional fields.
+ * Keep the total small — session cookies have a ~4KB size limit.
+ *
+ * **Staleness:** Data is snapshotted at login time. If a user's role
+ * or permissions change server-side, the cookie retains the old values
+ * until the user re-logs in. For authorization-critical fields (role,
+ * permissions, subscription tier), prefer `resolveUser` to get fresh
+ * data on every request.
+ *
+ * **ID type:** `user()` always returns `id` as a `string` on subsequent
+ * requests (read from cookie), even if the original `TUser.id` was a number.
+ */
+interface AuthConfigWithSessionFields<TUser extends AnyUser> extends AuthConfigBase<TUser> {
+    /** Cannot use `resolveUser` together with `sessionFields`. */
+    resolveUser?: never;
+    sessionFields: (keyof TUser & string)[];
+}
+export type AuthConfig<TUser extends AnyUser = AnyUser> = AuthConfigWithResolveUser<TUser> | AuthConfigWithSessionFields<TUser>;
 export interface HashConfig {
     rounds?: number;
 }
@@ -125,3 +131,4 @@ export interface RecoveryCodeResult {
     valid: boolean;
     remaining: string[];
 }
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ideal-auth",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Auth primitives for the JS ecosystem. Zero framework dependencies.",
   "scripts": {
     "build": "tsc",
@@ -25,17 +25,20 @@
     "skills"
   ],
   "dependencies": {
-    "iron-session": "^8.0.4",
-    "bcryptjs": "^3.0.3"
+    "iron-session": "^8.0.4"
   },
   "devDependencies": {
     "@types/bcryptjs": "^3.0.0",
     "@types/node": "^20"
   },
   "peerDependencies": {
+    "bcryptjs": "^3.0.3",
     "typescript": "^5.0.0"
   },
   "peerDependenciesMeta": {
+    "bcryptjs": {
+      "optional": true
+    },
     "typescript": {
       "optional": true
     }

package/skills/ideal-auth/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ideal-auth
-description: Auth primitives for the JS ecosystem. Covers login, logout, session, register, signup, sign in, sign out, password, 2FA, two-factor, TOTP, MFA, ideal-auth, cookie bridge, middleware, route protection, rate limit, rate limiting, password reset, forgot password, email verification, remember me, recovery code, CSRF, encrypt, decrypt, hash, bcrypt, token, secret, session cookie, multi-tenant, cross-domain, tenant, transfer token, federated logout, OAuth redirect, central login, login session, attemptUser, sessionFields, cookie-backed session, resolveUser, token refresh, refresh token, access token, OIDC.
+description: Auth primitives for the JS ecosystem. Covers login, logout, session, register, signup, sign in, sign out, password, 2FA, two-factor, TOTP, MFA, ideal-auth, cookie bridge, middleware, route protection, rate limit, rate limiting, password reset, forgot password, email verification, remember me, recovery code, CSRF, encrypt, decrypt, hash, bcrypt, token, secret, session cookie, multi-tenant, cross-domain, tenant, transfer token, federated logout, OAuth redirect, central login, login session, attemptUser, sessionFields, cookie-backed session, resolveUser, token refresh, refresh token, access token, OIDC, passkey, passkeys, WebAuthn, passwordless, biometric, fingerprint.
 ---
 
 You are an expert on `ideal-auth`, the auth primitives library for the JS ecosystem. You have complete knowledge of its API, patterns, security model, and framework integrations. Use this knowledge to help users implement authentication correctly.
@@ -194,27 +194,67 @@ const auth = createAuth({
 
 ---
 
-### `createHash(config?): HashInstance`
+### Password Hashing
 
-bcrypt password hashing with automatic SHA-256 prehash for passwords > 72 bytes.
+Password hashing is **only needed for the Laravel-style `attempt()` flow** (`hash` + `resolveUserByCredentials`). If you use `attemptUser`, `login(user)` directly, or `sessionFields` without credential verification, no `HashInstance` or `bcryptjs` is required.
 
-```typescript
-type HashConfig = { rounds?: number };  // default: 12
+ideal-auth accepts any `HashInstance`:
 
+```typescript
 type HashInstance = {
   make(password: string): Promise<string>;
   verify(password: string, hash: string): Promise<boolean>;
 };
 ```
 
+**`createHash()` (bcryptjs)** — built-in convenience. Requires `bcryptjs` as an optional peer dependency (`bun add bcryptjs`). Throws a clear error if not installed.
+
 ```typescript
 import { createHash } from 'ideal-auth';
 
-const hash = createHash({ rounds: 12 });
+const hash = createHash({ rounds: 12 }); // default: 12
 const hashed = await hash.make('password');
 const valid = await hash.verify('password', hashed); // true
 ```
 
+**Custom hash (bring your own)** — use your runtime's native hashing or a different algorithm. No `bcryptjs` needed.
+
+```typescript
+import { prehash } from 'ideal-auth';
+
+// Bun native bcrypt (faster than bcryptjs — use prehash for 72-byte limit)
+const hash: HashInstance = {
+  make: (password) => Bun.password.hash(prehash(password), { algorithm: 'bcrypt', cost: 12 }),
+  verify: (password, hash) => Bun.password.verify(prehash(password), hash),
+};
+
+// Bun argon2id (OWASP recommended — no prehash needed, no input length limit)
+const hash: HashInstance = {
+  make: (password) => Bun.password.hash(password, { algorithm: 'argon2id', memoryCost: 65536, timeCost: 2 }),
+  verify: (password, hash) => Bun.password.verify(password, hash),
+};
+
+// Node argon2 (requires: bun add argon2 — no prehash needed)
+import argon2 from 'argon2';
+const hash: HashInstance = {
+  make: (password) => argon2.hash(password),
+  verify: (password, hash) => argon2.verify(hash, password),
+};
+```
+
+Pass either to `createAuth`:
+
+```typescript
+const auth = createAuth({
+  secret: process.env.IDEAL_AUTH_SECRET!,
+  cookie: createCookieBridge(),
+  resolveUser: async (id) => db.user.findUnique({ where: { id } }),
+  hash, // createHash() or your custom HashInstance
+  resolveUserByCredentials: async (creds) =>
+    db.user.findUnique({ where: { email: creds.email } }),
+});
+```
+
 ---
 
 ### `createTokenVerifier(config): TokenVerifierInstance`
@@ -1582,6 +1622,53 @@ await auth().login(user, { remember: true });
 
 ---
 
+## Passkeys (WebAuthn)
+
+Passkeys use public-key cryptography for passwordless authentication. ideal-auth handles the session after verification — the WebAuthn protocol is handled by `@simplewebauthn/server` and `@simplewebauthn/browser`.
+
+No `hash` or `bcryptjs` needed — there are no passwords.
+
+### Flow
+
+```
+Registration: browser creates key pair → store public key in DB
+Authentication: server sends challenge → browser signs it → server verifies → auth().login(user)
+```
+
+### After WebAuthn verification, create session with ideal-auth
+
+```ts
+import { verifyAuthenticationResponse } from '@simplewebauthn/server';
+import { auth } from './auth';
+
+const verification = await verifyAuthenticationResponse({
+  response: body,
+  expectedChallenge,
+  expectedOrigin: origin,
+  expectedRPID: rpID,
+  credential: { id: passkey.id, publicKey: Buffer.from(passkey.publicKey, 'base64url'), counter: passkey.counter },
+});
+
+if (verification.verified) {
+  // Update signature counter (replay protection)
+  await db.passkey.update({ where: { id: passkey.id }, data: { counter: Number(verification.authenticationInfo.newCounter) } });
+
+  const user = await db.user.findUnique({ where: { id: passkey.userId } });
+  await auth().login(user); // session created — done
+}
+```
+
+### Key points
+- Install: `bun add @simplewebauthn/server @simplewebauthn/browser`
+- Store challenges in httpOnly cookies (5-min expiry), not client-side
+- Always update the signature counter after authentication
+- Set `rpID` to root domain (e.g., `example.com`) — works across subdomains
+- `userVerification: 'preferred'` for most apps, `'required'` for high-security
+- Passkeys with user verification can replace 2FA (biometric/PIN is the second factor)
+- Rate limit the options and verify endpoints
+
+---
+
 ## Open Redirect Prevention
 
 Always validate redirect URLs after login. Never redirect to user-supplied absolute URLs.