ideal-auth 0.5.1 → 0.6.1

package/README.md

@@ -99,7 +99,7 @@ Returns a function `auth()` that creates an `AuthInstance` on each call.
 | `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 \| undefined>` | No | — |
+| `resolveUserByCredentials` | `(creds: Record<string, any>) => Promise<AnyUser \| null \| undefined>` | No | — |
 | `credentialKey` | `string` | No | `'password'` |
 | `passwordField` | `string` | No | `'password'` |
 | `attemptUser` | `(creds: Record<string, any>) => Promise<User \| null \| undefined>` | No | — |

package/dist/auth-instance.d.ts

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

package/dist/auth-instance.js

@@ -40,10 +40,15 @@ export function createAuthInstance(deps) {
             : buildCookieOptions(maxAge, deps.cookieOptions);
         await deps.cookie.set(deps.cookieName, sealed, opts);
         cachedPayload = payload;
-        // When using sessionFields, only cache the picked fields (matching what's in the cookie)
-        cachedUser = payload.data
-            ? { id: user.id, ...payload.data }
-            : user;
+        if (payload.data) {
+            // sessionFields mode: cache only the picked fields
+            cachedUser = { id: user.id, ...payload.data };
+        }
+        else {
+            // resolveUser mode: strip the password field from cache
+            const { [deps.passwordField]: _, ...safeUser } = user;
+            cachedUser = safeUser;
+        }
     }
     return {
         async login(user, options) {
@@ -70,14 +75,14 @@ export function createAuthInstance(deps) {
             // Laravel-style: strip password, resolve user, verify hash
             if (deps.hash && deps.resolveUserByCredentials) {
                 const { [deps.credentialKey]: password, ...lookup } = credentials;
-                const user = await deps.resolveUserByCredentials(lookup);
-                if (!user)
+                const dbUser = await deps.resolveUserByCredentials(lookup);
+                if (!dbUser)
                     return false;
-                const storedHash = user[deps.passwordField];
+                const storedHash = dbUser[deps.passwordField];
                 if (!storedHash || !(await deps.hash.verify(password, storedHash))) {
                     return false;
                 }
-                await writeSession(user, options);
+                await writeSession(dbUser, options);
                 return true;
             }
             throw new Error('Provide either attemptUser() or both hash + resolveUserByCredentials in config to use attempt()');

package/dist/auth.d.ts

@@ -1,2 +1,13 @@
 import type { AnyUser, AuthInstance, AuthConfig } from './types';
-export declare function createAuth<TUser extends AnyUser = AnyUser>(config: AuthConfig<TUser>): () => AuthInstance<TUser>;
+/**
+ * Create an auth factory.
+ *
+ * @example
+ * // resolveUser — user() returns SafeUser
+ * createAuth<SafeUser>({ resolveUser: ... })
+ *
+ * // sessionFields — user() returns Pick<DbUser, 'id' | 'email' | 'name'>
+ * const sessionFields = ['email', 'name'] as const;
+ * createAuth<DbUser, (typeof sessionFields)[number]>({ sessionFields, ... })
+ */
+export declare function createAuth<TUser extends AnyUser, K extends keyof TUser & string = keyof TUser & string>(config: AuthConfig<TUser>): () => AuthInstance<TUser, Pick<TUser, 'id' | K>>;

package/dist/auth.js

@@ -4,6 +4,17 @@ const SESSION_DEFAULTS = {
     maxAge: 60 * 60 * 24 * 7, // 7 days
     rememberMaxAge: 60 * 60 * 24 * 30, // 30 days
 };
+/**
+ * Create an auth factory.
+ *
+ * @example
+ * // resolveUser — user() returns SafeUser
+ * createAuth<SafeUser>({ resolveUser: ... })
+ *
+ * // sessionFields — user() returns Pick<DbUser, 'id' | 'email' | 'name'>
+ * const sessionFields = ['email', 'name'] as const;
+ * createAuth<DbUser, (typeof sessionFields)[number]>({ sessionFields, ... })
+ */
 export function createAuth(config) {
     if (!config.secret || config.secret.length < 32) {
         throw new Error('secret must be at least 32 characters');

package/dist/index.d.ts

@@ -9,4 +9,4 @@ export { createRateLimiter } from './rate-limit';
 export { MemoryRateLimitStore } from './rate-limit/memory-store';
 export { createTOTP } from './totp';
 export { generateRecoveryCodes, verifyRecoveryCode } from './totp/recovery';
-export type { AnyUser, CookieBridge, ConfigurableCookieOptions, CookieOptions, SessionPayload, AuthConfig, HashConfig, LoginOptions, AuthInstance, HashInstance, TokenVerifierConfig, TokenVerifierInstance, RateLimitStore, RateLimiterConfig, RateLimitResult, TOTPConfig, TOTPInstance, RecoveryCodeResult, } from './types';
+export type { AnyUser, CookieBridge, ConfigurableCookieOptions, CookieOptions, SessionPayload, AuthConfig, AuthConfigWithResolveUser, AuthConfigWithSessionFields, HashConfig, LoginOptions, AuthInstance, HashInstance, TokenVerifierConfig, TokenVerifierInstance, RateLimitStore, RateLimiterConfig, RateLimitResult, TOTPConfig, TOTPInstance, RecoveryCodeResult, } from './types';

package/dist/types.d.ts

@@ -37,13 +37,19 @@ interface AuthConfigBase<TUser extends AnyUser> {
         cookie?: Partial<ConfigurableCookieOptions>;
     };
     hash?: HashInstance;
-    resolveUserByCredentials?: (credentials: Record<string, any>) => Promise<TUser | null | undefined>;
+    resolveUserByCredentials?: (credentials: Record<string, any>) => Promise<AnyUser | null | undefined>;
     credentialKey?: string;
     passwordField?: string;
     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> {
+/**
+ * Database-backed: `user()` calls `resolveUser(id)` on every request.
+ *
+ * `TUser` is the safe user type returned by `resolveUser` — this is what `user()` exposes.
+ * It should NOT include sensitive fields like password.
+ * `resolveUserByCredentials` can return any shape (it only needs id + password field for verification).
+ */
+export interface AuthConfigWithResolveUser<TUser extends AnyUser> extends AuthConfigBase<TUser> {
     resolveUser: (id: string) => Promise<TUser | null | undefined>;
     /** Cannot use `sessionFields` together with `resolveUser`. */
     sessionFields?: never;
@@ -63,22 +69,22 @@ interface AuthConfigWithResolveUser<TUser extends AnyUser> extends AuthConfigBas
  * **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> {
+export interface AuthConfigWithSessionFields<TUser extends AnyUser, K extends keyof TUser & string = keyof TUser & string> extends AuthConfigBase<TUser> {
     /** Cannot use `resolveUser` together with `sessionFields`. */
     resolveUser?: never;
-    sessionFields: (keyof TUser & string)[];
+    sessionFields: readonly K[];
 }
 export type AuthConfig<TUser extends AnyUser = AnyUser> = AuthConfigWithResolveUser<TUser> | AuthConfigWithSessionFields<TUser>;
 export interface HashConfig {
     rounds?: number;
 }
-export interface AuthInstance<TUser extends AnyUser = AnyUser> {
+export interface AuthInstance<TUser extends AnyUser = AnyUser, TSessionUser = TUser> {
     login(user: TUser, options?: LoginOptions): Promise<void>;
     loginById(id: string, options?: LoginOptions): Promise<void>;
     attempt(credentials: Record<string, any>, options?: LoginOptions): Promise<boolean>;
     logout(): Promise<void>;
     check(): Promise<boolean>;
-    user(): Promise<TUser | null>;
+    user(): Promise<TSessionUser | null>;
     id(): Promise<string | null>;
 }
 export interface HashInstance {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ideal-auth",
-  "version": "0.5.1",
+  "version": "0.6.1",
   "description": "Auth primitives for the JS ecosystem. Zero framework dependencies.",
   "scripts": {
     "build": "tsc",
@@ -29,6 +29,7 @@
   },
   "devDependencies": {
     "@types/bcryptjs": "^3.0.0",
+    "@types/bun": "^1.3.11",
     "@types/node": "^20"
   },
   "peerDependencies": {

package/skills/ideal-auth/SKILL.md

@@ -71,70 +71,87 @@ Returns a factory function. Call `auth()` per request to get an `AuthInstance` s
 #### AuthConfig
 
 ```typescript
-type AuthConfig<TUser extends AnyUser> = {
-  secret: string;                    // 32+ chars, required — throws if shorter
-  cookie: CookieBridge;              // required
-
-  // Session mode — provide exactly ONE of these two:
-  resolveUser?: (id: string) => Promise<TUser | null>;  // DB-backed: user() calls this every request
-  sessionFields?: (keyof TUser & string)[];              // Cookie-backed: user() reads from cookie, zero external calls
-
-  // Session options
-  session?: {
-    cookieName?: string;             // default: 'ideal_session'
-    maxAge?: number;                 // default: 604800 (7 days, in seconds)
-    rememberMaxAge?: number;         // default: 2592000 (30 days, in seconds)
-    cookie?: Partial<ConfigurableCookieOptions>;
-  };
-
-  // Laravel-style attempt (recommended)
+// Session mode — provide exactly ONE of resolveUser or sessionFields
+// TypeScript will error if you provide both or neither
+
+// resolveUser mode: TUser is the safe type returned by resolveUser and user()
+type AuthConfigWithResolveUser<TUser> = {
+  secret: string;
+  cookie: CookieBridge;
+  resolveUser: (id: string) => Promise<TUser | null | undefined>;
+  sessionFields?: never;
+  // resolveUserByCredentials can return any shape — only needs id + passwordField
+  resolveUserByCredentials?: (credentials: Record<string, any>) => Promise<AnyUser | null | undefined>;
   hash?: HashInstance;
-  resolveUserByCredentials?: (credentials: Record<string, any>) => Promise<TUser | null>;
-  credentialKey?: string;            // default: 'password'
-  passwordField?: string;            // default: 'password'
+  attemptUser?: (credentials: Record<string, any>) => Promise<TUser | null | undefined>;
+  // ...session options
+};
 
-  // Manual attempt (escape hatch — takes precedence if both provided)
-  attemptUser?: (credentials: Record<string, any>) => Promise<TUser | null>;
+// sessionFields mode: user() returns Pick<TUser, 'id' | K>
+type AuthConfigWithSessionFields<TUser, K extends keyof TUser> = {
+  secret: string;
+  cookie: CookieBridge;
+  resolveUser?: never;
+  sessionFields: K[];
+  resolveUserByCredentials?: (credentials: Record<string, any>) => Promise<AnyUser | null | undefined>;
+  hash?: HashInstance;
+  attemptUser?: (credentials: Record<string, any>) => Promise<TUser | null | undefined>;
+  // ...session options
 };
 ```
 
 #### Session Modes
 
-**Database-backed (`resolveUser`):** Cookie stores only user ID. `user()` calls `resolveUser(id)` every request. Best for real-time data freshness.
+**Database-backed (`resolveUser`):** Cookie stores only user ID. `user()` calls `resolveUser(id)` every request. Type `TUser` as the safe type — only select non-sensitive columns.
 
 ```typescript
-const auth = createAuth<User>({
+type SafeUser = { id: string; email: string; name: string; role: string };
+
+const auth = createAuth<SafeUser>({
   secret: process.env.IDEAL_AUTH_SECRET!,
   cookie: createCookieBridge(),
-  resolveUser: async (id) => db.user.findUnique({ where: { id } }),
+  // Returns SafeUser — no password
+  resolveUser: async (id) => db.user.findFirst({
+    where: { id },
+    columns: { id: true, email: true, name: true, role: true },
+  }),
+  // Can return full DB row — only used internally for hash verification
+  resolveUserByCredentials: async (creds) => db.user.findFirst({
+    where: { email: creds.email },
+  }),
   hash,
-  resolveUserByCredentials: async (creds) =>
-    db.user.findUnique({ where: { email: creds.email } }),
 });
+const user = await auth().user(); // Type: SafeUser | null
 ```
 
-**Cookie-backed (`sessionFields`):** Cookie stores user ID + declared fields. `user()` reads from cookie — zero external calls. Best for performance, stateless apps, or apps without a database.
+**Cookie-backed (`sessionFields`):** Cookie stores user ID + declared fields. `user()` returns `Pick<TUser, 'id' | K>` — password excluded from the type.
+
+Define fields once as `const` and derive the type with `(typeof sessionFields)[number]`:
 
 ```typescript
-const auth = createAuth<User>({
+type DbUser = { id: string; email: string; name: string; role: string; password: string };
+
+const sessionFields = ['email', 'name', 'role'] as const;
+
+const auth = createAuth<DbUser, (typeof sessionFields)[number]>({
   secret: process.env.IDEAL_AUTH_SECRET!,
   cookie: createCookieBridge(),
-  sessionFields: ['email', 'name', 'role'],
+  sessionFields,
+  resolveUserByCredentials: async (creds) => db.user.findFirst({ where: { email: creds.email } }),
   hash,
-  resolveUserByCredentials: async (creds) =>
-    db.user.findUnique({ where: { email: creds.email } }),
 });
-// user() returns { id, email, name, role } from cookie
+const user = await auth().user(); // Type: Pick<DbUser, 'id' | 'email' | 'name' | 'role'> | null
 ```
 
 Key rules:
-- Provide exactly one of `resolveUser` or `sessionFields` — both or neither throws
-- `id` is always stored — don't include it in `sessionFields`
+- Provide exactly one of `resolveUser` or `sessionFields` — TypeScript errors if both or neither
+- `resolveUser` mode: `TUser` is the safe type. Only select non-sensitive fields in your query
+- `sessionFields` mode: `user()` type is `Pick<TUser, 'id' | ...fields>` — password excluded automatically
+- `resolveUserByCredentials` returns `AnyUser` — doesn't need to match `TUser`, only needs `id` + password field
+- Password is stripped from the cached user after `attempt()` — even same-request `user()` won't expose it
 - Cookie limit is ~4KB — store basic fields only
-- `sessionFields` data is a snapshot from login time — stale if user updates profile mid-session
-- To refresh, call `auth().login(updatedUser)` after the update
 - `loginById()` requires `resolveUser` — throws with `sessionFields`
-- Both modes work with `attempt()`, `attemptUser`, `hash + resolveUserByCredentials`
+- Never pass `user()` directly to the client — always pick the specific fields you need
 
 #### AuthInstance Methods