ideal-auth 0.1.0 → 0.3.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

@@ -2,6 +2,8 @@
 
 Auth primitives for the JS ecosystem. Zero framework dependencies. Inspired by Laravel's `Auth` and `Hash` facades.
 
+**[Documentation](https://ramonmalcolm10.github.io/ideal-auth/)**
+
 Provide a cookie bridge (3 functions) once during setup, and `auth().login(user)` just works — handles session creation, cookie encryption, and storage internally via [iron-session](https://github.com/vvo/iron-session).
 
 ## Install
@@ -475,7 +477,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,11 +519,23 @@ cookie: {
 
 | Package | Purpose |
 | --- | --- |
-| `iron-session` | Session sealing/unsealing (AES-256-GCM + HMAC) |
+| `iron-session` | Session sealing/unsealing (AES-256-CBC + HMAC) |
 | `bcryptjs` | Password hashing |
 
 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/bin/ideal-auth.js

@@ -5,9 +5,13 @@ switch (command) {
     case 'secret':
         console.log(`IDEAL_AUTH_SECRET=${randomBytes(32).toString('base64url')}`);
         break;
+    case 'encryption-key':
+        console.log(`ENCRYPTION_KEY=${randomBytes(32).toString('hex')}`);
+        break;
     default:
         console.log('Usage: ideal-auth <command>\n');
         console.log('Commands:');
-        console.log('  secret    Generate an IDEAL_AUTH_SECRET for your .env file');
+        console.log('  secret          Generate an IDEAL_AUTH_SECRET for your .env file');
+        console.log('  encryption-key  Generate an ENCRYPTION_KEY for encrypting data at rest');
         break;
 }

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.1.0",
+  "version": "0.3.0",
   "description": "Auth primitives for the JS ecosystem. Zero framework dependencies.",
   "scripts": {
     "build": "tsc",
@@ -20,7 +20,9 @@
     "ideal-auth": "./dist/bin/ideal-auth.js"
   },
   "files": [
-    "dist"
+    "dist",
+    ".claude-plugin",
+    "skills"
   ],
   "dependencies": {
     "iron-session": "^8.0.4",