ideal-auth 0.2.0 → 0.4.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "ideal-auth",
+  "description": "Auth primitives for the JS ecosystem. Provides complete API reference, cookie bridge patterns for every framework, security best practices, and implementation guides for ideal-auth.",
+  "author": "Ramon Malcolm"
+}

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
@@ -477,7 +502,7 @@ const limiter = createRateLimiter({
 
 ## How It Works
 
-Sessions are **stateless, encrypted cookies** powered by iron-session (AES-256-GCM + HMAC integrity).
+Sessions are **stateless, encrypted cookies** powered by iron-session (AES-256-CBC + HMAC integrity).
 
 1. **`login(user)`** — Creates a `SessionPayload { uid, iat, exp }`, seals it with iron-session, writes the encrypted string to the cookie via the bridge.
 2. **`check()` / `user()` / `id()`** — Reads the cookie via the bridge, unseals the payload, checks expiry. `user()` additionally calls `resolveUser(id)` to fetch the full user.
@@ -517,13 +542,25 @@ cookie: {
 
 ## Dependencies
 
-| Package | Purpose |
-| --- | --- |
-| `iron-session` | Session sealing/unsealing (AES-256-GCM + 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.
 
+## Claude Code
+
+If you use [Claude Code](https://claude.com/claude-code), install the ideal-auth plugin so your AI assistant knows the full API, cookie bridge patterns, security best practices, and implementation guides:
+
+```bash
+claude plugin install github:ramonmalcolm10/ideal-auth
+```
+
+After installing, Claude Code will automatically help with auth setup, login/registration flows, middleware, 2FA, password reset, rate limiting, and more — using the correct patterns for your framework.
+
+---
+
 ## Support
 
 If this saved you time, consider supporting the project:

package/dist/auth-instance.d.ts

@@ -6,7 +6,8 @@ interface AuthInstanceDeps<TUser extends AnyUser> {
     maxAge: number;
     rememberMaxAge: number;
     cookieOptions: ConfigurableCookieOptions;
-    resolveUser: (id: string) => Promise<TUser | null>;
+    resolveUser?: (id: string) => Promise<TUser | null>;
+    sessionFields?: (keyof TUser & string)[];
     hash?: HashInstance;
     resolveUserByCredentials?: (credentials: Record<string, any>) => Promise<TUser | null>;
     credentialKey: string;

package/dist/auth-instance.js

@@ -14,6 +14,17 @@ export function createAuthInstance(deps) {
         cachedPayload = await unseal(raw, deps.secret);
         return cachedPayload;
     }
+    function pickSessionData(user) {
+        if (!deps.sessionFields)
+            return undefined;
+        const data = {};
+        for (const field of deps.sessionFields) {
+            if (field !== 'id' && field in user) {
+                data[field] = user[field];
+            }
+        }
+        return Object.keys(data).length > 0 ? data : undefined;
+    }
     async function writeSession(user, options) {
         const maxAge = options?.remember ? deps.rememberMaxAge : deps.maxAge;
         const now = Math.floor(Date.now() / 1000);
@@ -21,6 +32,7 @@ export function createAuthInstance(deps) {
             uid: String(user.id),
             iat: now,
             exp: now + maxAge,
+            data: pickSessionData(user),
         };
         const sealed = await seal(payload, deps.secret);
         const opts = options?.remember === false
@@ -28,13 +40,19 @@ export function createAuthInstance(deps) {
             : buildCookieOptions(maxAge, deps.cookieOptions);
         await deps.cookie.set(deps.cookieName, sealed, opts);
         cachedPayload = payload;
-        cachedUser = user;
+        // When using sessionFields, only cache the picked fields (matching what's in the cookie)
+        cachedUser = payload.data
+            ? { id: user.id, ...payload.data }
+            : user;
     }
     return {
         async login(user, options) {
             await writeSession(user, options);
         },
         async loginById(id, options) {
+            if (!deps.resolveUser) {
+                throw new Error('loginById requires resolveUser — use login(user) instead when using sessionFields');
+            }
             const user = await deps.resolveUser(id);
             if (!user)
                 throw new Error('Login failed');
@@ -81,7 +99,17 @@ export function createAuthInstance(deps) {
                 cachedUser = null;
                 return null;
             }
-            cachedUser = await deps.resolveUser(session.uid);
+            // Cookie-backed: reconstruct user from session data
+            if (deps.sessionFields && session.data) {
+                cachedUser = { id: session.uid, ...session.data };
+                return cachedUser;
+            }
+            // Database-backed: resolve user via callback
+            if (deps.resolveUser) {
+                cachedUser = await deps.resolveUser(session.uid);
+                return cachedUser;
+            }
+            cachedUser = null;
             return cachedUser;
         },
         async id() {

package/dist/auth.js

@@ -8,6 +8,15 @@ export function createAuth(config) {
     if (!config.secret || config.secret.length < 32) {
         throw new Error('secret must be at least 32 characters');
     }
+    if (config.resolveUser && config.sessionFields) {
+        throw new Error('Provide either resolveUser or sessionFields, not both');
+    }
+    if (!config.resolveUser && !config.sessionFields) {
+        throw new Error('Provide either resolveUser or sessionFields');
+    }
+    if (config.sessionFields && config.sessionFields.filter((f) => f !== 'id').length === 0) {
+        throw new Error('sessionFields must contain at least one field besides id');
+    }
     return () => createAuthInstance({
         secret: config.secret,
         cookie: config.cookie,
@@ -16,6 +25,7 @@ export function createAuth(config) {
         rememberMaxAge: config.session?.rememberMaxAge ?? SESSION_DEFAULTS.rememberMaxAge,
         cookieOptions: config.session?.cookie ?? {},
         resolveUser: config.resolveUser,
+        sessionFields: config.sessionFields,
         hash: config.hash,
         resolveUserByCredentials: config.resolveUserByCredentials,
         credentialKey: config.credentialKey ?? 'password',

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/session/seal.js

@@ -11,7 +11,12 @@ export async function unseal(sealed, secret) {
             return null;
         if (data.exp < Math.floor(Date.now() / 1000))
             return null;
-        return data;
+        return {
+            uid: data.uid,
+            iat: data.iat,
+            exp: data.exp,
+            ...(data.data !== undefined && { data: data.data }),
+        };
     }
     catch {
         return null;

package/dist/types.d.ts

@@ -22,6 +22,7 @@ export interface SessionPayload {
     uid: string;
     iat: number;
     exp: number;
+    data?: Record<string, unknown>;
 }
 export interface LoginOptions {
     remember?: boolean;
@@ -35,7 +36,27 @@ export interface AuthConfig<TUser extends AnyUser = AnyUser> {
         rememberMaxAge?: number;
         cookie?: Partial<ConfigurableCookieOptions>;
     };
-    resolveUser: (id: string) => Promise<TUser | null>;
+    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>;
     credentialKey?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ideal-auth",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Auth primitives for the JS ecosystem. Zero framework dependencies.",
   "scripts": {
     "build": "tsc",
@@ -20,20 +20,25 @@
     "ideal-auth": "./dist/bin/ideal-auth.js"
   },
   "files": [
-    "dist"
+    "dist",
+    ".claude-plugin",
+    "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
     }