ideal-auth 0.6.0 → 0.7.0

package/README.md

@@ -552,18 +552,6 @@ cookie: {
 
 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.d.ts

@@ -1,5 +1,12 @@
-import type { AnyUser, AuthInstance, AuthConfigWithResolveUser, AuthConfigWithSessionFields } from './types';
-/** Database-backed: `user()` returns `TUser` (the safe type from `resolveUser`). */
-export declare function createAuth<TUser extends AnyUser>(config: AuthConfigWithResolveUser<TUser>): () => AuthInstance<TUser>;
-/** Cookie-backed: `user()` returns only `id` + the declared `sessionFields`. */
-export declare function createAuth<TUser extends AnyUser, K extends keyof TUser & string>(config: AuthConfigWithSessionFields<TUser, K>): () => AuthInstance<TUser, Pick<TUser, 'id' | K>>;
+import type { AnyUser, AuthInstance, AuthConfig } from './types';
+/**
+ * Create an auth factory.
+ *
+ * `TUser` is the session user type — what `user()` returns.
+ * Do not include sensitive fields like password in this type.
+ *
+ * @example
+ * type SessionUser = { id: string; email: string; name: string };
+ * createAuth<SessionUser>({ ... })
+ */
+export declare function createAuth<TUser extends AnyUser>(config: AuthConfig<TUser>): () => AuthInstance<TUser>;

package/dist/auth.js

@@ -4,6 +4,16 @@ const SESSION_DEFAULTS = {
     maxAge: 60 * 60 * 24 * 7, // 7 days
     rememberMaxAge: 60 * 60 * 24 * 30, // 30 days
 };
+/**
+ * Create an auth factory.
+ *
+ * `TUser` is the session user type — what `user()` returns.
+ * Do not include sensitive fields like password in this type.
+ *
+ * @example
+ * type SessionUser = { id: string; email: string; name: string };
+ * createAuth<SessionUser>({ ... })
+ */
 export function createAuth(config) {
     if (!config.secret || config.secret.length < 32) {
         throw new Error('secret must be at least 32 characters');

package/dist/types.d.ts

@@ -78,13 +78,13 @@ export type AuthConfig<TUser extends AnyUser = AnyUser> = AuthConfigWithResolveU
 export interface HashConfig {
     rounds?: number;
 }
-export interface AuthInstance<TUser extends AnyUser = AnyUser, TSessionUser = TUser> {
+export interface AuthInstance<TUser extends AnyUser = AnyUser> {
     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<TSessionUser | null>;
+    user(): Promise<TUser | null>;
     id(): Promise<string | null>;
 }
 export interface HashInstance {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ideal-auth",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Auth primitives for the JS ecosystem. Zero framework dependencies.",
   "scripts": {
     "build": "tsc",

package/skills/ideal-auth/SKILL.md

@@ -71,33 +71,28 @@ Returns a factory function. Call `auth()` per request to get an `AuthInstance` s
 #### AuthConfig
 
 ```typescript
-// 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;
-  attemptUser?: (credentials: Record<string, any>) => Promise<TUser | null | undefined>;
-  // ...session options
-};
-
-// 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
-};
+// TUser = session user type — what user() returns. Do not include password.
+// Provide exactly ONE of resolveUser or sessionFields.
+// TypeScript will error if you provide both or neither.
+
+type AuthConfig<TUser> =
+  | {
+      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;
+      attemptUser?: (credentials: Record<string, any>) => Promise<TUser | null | undefined>;
+      // ...session, secret, cookie
+    }
+  | {
+      resolveUser?: never;
+      sessionFields: (keyof TUser & string)[];
+      resolveUserByCredentials?: (credentials: Record<string, any>) => Promise<AnyUser | null | undefined>;
+      hash?: HashInstance;
+      attemptUser?: (credentials: Record<string, any>) => Promise<TUser | null | undefined>;
+      // ...session, secret, cookie
+    };
 ```
 
 #### Session Modes
@@ -124,25 +119,24 @@ const auth = createAuth<SafeUser>({
 const user = await auth().user(); // Type: SafeUser | null
 ```
 
-**Cookie-backed (`sessionFields`):** Cookie stores user ID + declared fields. `user()` returns `Pick<TUser, 'id' | K>` — password excluded from the type.
+**Cookie-backed (`sessionFields`):** Cookie stores user ID + declared fields. `user()` returns `TUser | null`. Since `TUser` should not include password, the type is already safe.
 
 ```typescript
-type DbUser = { id: string; email: string; name: string; role: string; password: string };
+type SessionUser = { id: string; email: string; name: string; role: string }; // no password
 
-const auth = createAuth<DbUser>({
+const auth = createAuth<SessionUser>({
   secret: process.env.IDEAL_AUTH_SECRET!,
   cookie: createCookieBridge(),
   sessionFields: ['email', 'name', 'role'],
   resolveUserByCredentials: async (creds) => db.user.findFirst({ where: { email: creds.email } }),
   hash,
 });
-const user = await auth().user(); // Type: Pick<DbUser, 'id' | 'email' | 'name' | 'role'> | null
+const user = await auth().user(); // Type: SessionUser | null
 ```
 
 Key rules:
+- `TUser` is the session user type — what `user()` returns. Do not include password.
 - 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