ideal-auth 0.3.0 → 0.4.0

package/README.md

@@ -171,7 +171,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 +190,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 +542,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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ideal-auth",
-  "version": "0.3.0",
+  "version": "0.4.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

@@ -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`