ideal-auth 0.6.1 → 1.0.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-instance.d.ts

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

package/dist/auth-instance.js

@@ -121,5 +121,22 @@ export function createAuthInstance(deps) {
             const session = await readSession();
             return session?.uid ?? null;
         },
+        async touch() {
+            const session = await readSession();
+            if (!session)
+                return;
+            const maxAge = session.exp - session.iat;
+            const now = Math.floor(Date.now() / 1000);
+            const newPayload = {
+                uid: session.uid,
+                iat: session.iat, // preserve original issued-at for passwordChangedAt checks
+                exp: now + maxAge,
+                ...(session.data !== undefined && { data: session.data }),
+            };
+            const sealed = await seal(newPayload, deps.secret);
+            const opts = buildCookieOptions(maxAge, deps.cookieOptions);
+            await deps.cookie.set(deps.cookieName, sealed, opts);
+            cachedPayload = newPayload;
+        },
     };
 }

package/dist/auth.d.ts

@@ -2,12 +2,11 @@ import type { AnyUser, AuthInstance, AuthConfig } from './types';
 /**
  * Create an auth factory.
  *
- * @example
- * // resolveUser — user() returns SafeUser
- * createAuth<SafeUser>({ resolveUser: ... })
+ * `TUser` is the session user type — what `user()` returns.
+ * Do not include sensitive fields like password in this type.
  *
- * // sessionFields — user() returns Pick<DbUser, 'id' | 'email' | 'name'>
- * const sessionFields = ['email', 'name'] as const;
- * createAuth<DbUser, (typeof sessionFields)[number]>({ sessionFields, ... })
+ * @example
+ * type SessionUser = { id: string; email: string; name: string };
+ * createAuth<SessionUser>({ ... })
  */
-export declare function createAuth<TUser extends AnyUser, K extends keyof TUser & string = keyof TUser & string>(config: AuthConfig<TUser>): () => AuthInstance<TUser, Pick<TUser, 'id' | K>>;
+export declare function createAuth<TUser extends AnyUser>(config: AuthConfig<TUser>): () => AuthInstance<TUser>;

package/dist/auth.js

@@ -7,13 +7,12 @@ const SESSION_DEFAULTS = {
 /**
  * Create an auth factory.
  *
- * @example
- * // resolveUser — user() returns SafeUser
- * createAuth<SafeUser>({ resolveUser: ... })
+ * `TUser` is the session user type — what `user()` returns.
+ * Do not include sensitive fields like password in this type.
  *
- * // sessionFields — user() returns Pick<DbUser, 'id' | 'email' | 'name'>
- * const sessionFields = ['email', 'name'] as const;
- * createAuth<DbUser, (typeof sessionFields)[number]>({ sessionFields, ... })
+ * @example
+ * type SessionUser = { id: string; email: string; name: string };
+ * createAuth<SessionUser>({ ... })
  */
 export function createAuth(config) {
     if (!config.secret || config.secret.length < 32) {

package/dist/types.d.ts

@@ -72,20 +72,22 @@ export interface AuthConfigWithResolveUser<TUser extends AnyUser> extends AuthCo
 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: readonly K[];
+    sessionFields: K[];
 }
 export type AuthConfig<TUser extends AnyUser = AnyUser> = AuthConfigWithResolveUser<TUser> | AuthConfigWithSessionFields<TUser>;
 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>;
+    /** Re-seal the session cookie with a fresh expiry. No database call needed. Does nothing if no valid session exists. */
+    touch(): Promise<void>;
 }
 export interface HashInstance {
     make(password: string): Promise<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ideal-auth",
-  "version": "0.6.1",
+  "version": "1.0.0",
   "description": "Auth primitives for the JS ecosystem. Zero framework dependencies.",
   "scripts": {
     "build": "tsc",
@@ -51,5 +51,32 @@
     "type": "git",
     "url": "git+https://github.com/ramonmalcolm10/ideal-auth.git"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "keywords": [
+    "auth",
+    "authentication",
+    "session",
+    "cookie",
+    "login",
+    "password",
+    "bcrypt",
+    "argon2",
+    "hash",
+    "totp",
+    "2fa",
+    "two-factor",
+    "mfa",
+    "rate-limit",
+    "csrf",
+    "encryption",
+    "iron-session",
+    "nextjs",
+    "sveltekit",
+    "express",
+    "hono",
+    "nuxt",
+    "bun",
+    "passkey",
+    "webauthn"
+  ]
 }

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,29 +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.
-
-Define fields once as `const` and derive the type with `(typeof sessionFields)[number]`:
+**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 };
-
-const sessionFields = ['email', 'name', 'role'] as const;
+type SessionUser = { id: string; email: string; name: string; role: string }; // no password
 
-const auth = createAuth<DbUser, (typeof sessionFields)[number]>({
+const auth = createAuth<SessionUser>({
   secret: process.env.IDEAL_AUTH_SECRET!,
   cookie: createCookieBridge(),
-  sessionFields,
+  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
@@ -164,6 +154,7 @@ Key rules:
 | `check()` | `Promise<boolean>` | Is the session valid? (fast, cached) |
 | `user()` | `Promise<TUser \| null>` | Get the authenticated user (from DB with `resolveUser`, or from cookie with `sessionFields`) |
 | `id()` | `Promise<string \| null>` | Get the authenticated user's ID |
+| `touch()` | `Promise<void>` | Re-seal the session cookie with a fresh expiry. No database call needed. |
 
 #### LoginOptions
 
@@ -176,6 +167,20 @@ type LoginOptions = {
 };
 ```
 
+#### Session Extension with `touch()`
+
+Sessions have a fixed expiry. Call `touch()` in middleware to extend the session for active users:
+
+```typescript
+// In middleware — where cookie writes are allowed
+const session = auth();
+if (await session.check()) {
+  await session.touch(); // re-seals cookie with fresh exp
+}
+```
+
+`touch()` re-seals with the same `maxAge` as the original session. No database call needed. `check()`, `user()`, and `id()` are read-only — they never write cookies. Only call `touch()` where cookie writes are allowed (middleware, route handlers, server actions — NOT Server Components).
+
 #### `attempt()` — Two Modes
 
 **Laravel-style (recommended):** Provide `hash` and `resolveUserByCredentials`. The `attempt()` method strips the credential key (default `'password'`) from credentials, looks up the user with remaining fields, and verifies the hash automatically.