ideal-auth 1.0.0 → 1.1.0

package/README.md

@@ -106,6 +106,7 @@ Returns a function `auth()` that creates an `AuthInstance` on each call.
 | `session.cookieName` | `string` | No | `'ideal_session'` |
 | `session.maxAge` | `number` (seconds) | No | `604800` (7 days) |
 | `session.rememberMaxAge` | `number` (seconds) | No | `2592000` (30 days) |
+| `session.autoTouch` | `boolean` | No | `false`. Auto-extend sessions past halfway on `check()`/`user()`/`id()`. Enable for Express/Hono. Disable for Next.js. |
 | `session.cookie` | `Partial<ConfigurableCookieOptions>` | No | secure in prod, sameSite lax, path / (`httpOnly` is always `true` — not configurable) |
 
 #### AuthInstance Methods
@@ -116,9 +117,10 @@ Returns a function `auth()` that creates an `AuthInstance` on each call.
 | `loginById(id, options?)` | `Promise<void>` | Resolve user by ID, then set session cookie |
 | `attempt(credentials, options?)` | `Promise<boolean>` | Find user, verify password, login if valid |
 | `logout()` | `Promise<void>` | Delete session cookie |
-| `check()` | `Promise<boolean>` | Is the session valid? |
-| `user()` | `Promise<User \| null>` | Get the authenticated user |
-| `id()` | `Promise<string \| null>` | Get the authenticated user's ID |
+| `check()` | `Promise<boolean>` | Is the session valid? (read-only) |
+| `user()` | `Promise<User \| null>` | Get the authenticated user (read-only) |
+| `id()` | `Promise<string \| null>` | Get the authenticated user's ID (read-only) |
+| `touch()` | `Promise<void>` | Extend session expiry. Reseals past halfway (`autoTouch: false`) or immediately (`autoTouch: true`). |
 
 All login methods accept an optional `LoginOptions` object:
 

package/dist/auth-instance.d.ts

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

package/dist/auth-instance.js

@@ -3,6 +3,7 @@ import { buildCookieOptions } from './session/cookie';
 export function createAuthInstance(deps) {
     let cachedPayload;
     let cachedUser;
+    let didAutoTouch = false;
     async function readSession() {
         if (cachedPayload !== undefined)
             return cachedPayload;
@@ -12,8 +13,31 @@ export function createAuthInstance(deps) {
             return null;
         }
         cachedPayload = await unseal(raw, deps.secret);
+        // Auto-touch: reseal past halfway when enabled
+        if (deps.autoTouch && cachedPayload && !didAutoTouch) {
+            const elapsed = Math.floor(Date.now() / 1000) - cachedPayload.iat;
+            if (elapsed >= cachedPayload.ttl / 2) {
+                await resealSession(cachedPayload);
+            }
+        }
         return cachedPayload;
     }
+    async function resealSession(session) {
+        didAutoTouch = true;
+        const ttl = session.ttl;
+        const now = Math.floor(Date.now() / 1000);
+        const newPayload = {
+            uid: session.uid,
+            iat: session.iat, // preserve original issued-at for passwordChangedAt checks
+            exp: now + ttl,
+            ttl,
+            ...(session.data !== undefined && { data: session.data }),
+        };
+        const sealed = await seal(newPayload, deps.secret);
+        const opts = buildCookieOptions(ttl, deps.cookieOptions);
+        await deps.cookie.set(deps.cookieName, sealed, opts);
+        cachedPayload = newPayload;
+    }
     function pickSessionData(user) {
         if (!deps.sessionFields)
             return undefined;
@@ -32,6 +56,7 @@ export function createAuthInstance(deps) {
             uid: String(user.id),
             iat: now,
             exp: now + maxAge,
+            ttl: maxAge,
             data: pickSessionData(user),
         };
         const sealed = await seal(payload, deps.secret);
@@ -125,18 +150,16 @@ export function createAuthInstance(deps) {
             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;
+            if (didAutoTouch)
+                return; // already resealed by autoTouch on this request
+            // autoTouch enabled: reseal immediately (user opted in to cookie writes)
+            // autoTouch disabled: only reseal past halfway (conservative)
+            if (!deps.autoTouch) {
+                const elapsed = Math.floor(Date.now() / 1000) - session.iat;
+                if (elapsed < session.ttl / 2)
+                    return;
+            }
+            await resealSession(session);
         },
     };
 }

package/dist/auth.js

@@ -34,6 +34,7 @@ export function createAuth(config) {
         maxAge: config.session?.maxAge ?? SESSION_DEFAULTS.maxAge,
         rememberMaxAge: config.session?.rememberMaxAge ?? SESSION_DEFAULTS.rememberMaxAge,
         cookieOptions: config.session?.cookie ?? {},
+        autoTouch: config.session?.autoTouch ?? false,
         resolveUser: config.resolveUser,
         sessionFields: config.sessionFields,
         hash: config.hash,

package/dist/session/seal.js

@@ -15,6 +15,7 @@ export async function unseal(sealed, secret) {
             uid: data.uid,
             iat: data.iat,
             exp: data.exp,
+            ttl: (typeof data.ttl === 'number' && data.ttl > 0) ? data.ttl : (data.exp - data.iat),
             ...(data.data !== undefined && { data: data.data }),
         };
     }

package/dist/types.d.ts

@@ -22,6 +22,7 @@ export interface SessionPayload {
     uid: string;
     iat: number;
     exp: number;
+    ttl: number;
     data?: Record<string, unknown>;
 }
 export interface LoginOptions {
@@ -35,6 +36,8 @@ interface AuthConfigBase<TUser extends AnyUser> {
         maxAge?: number;
         rememberMaxAge?: number;
         cookie?: Partial<ConfigurableCookieOptions>;
+        /** Automatically extend session on read when past the halfway point. Default: false. */
+        autoTouch?: boolean;
     };
     hash?: HashInstance;
     resolveUserByCredentials?: (credentials: Record<string, any>) => Promise<AnyUser | null | undefined>;
@@ -86,7 +89,7 @@ export interface AuthInstance<TUser extends AnyUser = AnyUser> {
     check(): Promise<boolean>;
     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. */
+    /** Re-seal the session cookie with a fresh expiry. When autoTouch is disabled (default), only reseals past the halfway point. No database call needed. Does nothing if no valid session exists or if already resealed on this request. */
     touch(): Promise<void>;
 }
 export interface HashInstance {

package/package.json

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

package/skills/ideal-auth/SKILL.md

@@ -167,19 +167,34 @@ type LoginOptions = {
 };
 ```
 
-#### Session Extension with `touch()`
+#### Session Extension
 
-Sessions have a fixed expiry. Call `touch()` in middleware to extend the session for active users:
+Two options for keeping active users logged in:
+
+**`autoTouch: true`** — automatic. Enable for Express, Hono, Elysia, SvelteKit. `check()`/`user()`/`id()` auto-reseal past halfway. Do NOT use with Next.js (Server Components can't write cookies).
+
+```typescript
+const auth = createAuth<User>({
+  session: { autoTouch: true },
+  ...
+});
+```
+
+**Manual `touch()`** — call in middleware. When `autoTouch` is false (default), only reseals past halfway. When `autoTouch` is true, reseals immediately.
 
 ```typescript
-// In middleware — where cookie writes are allowed
 const session = auth();
 if (await session.check()) {
-  await session.touch(); // re-seals cookie with fresh exp
+  await session.touch();
 }
 ```
 
-`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).
+| | `autoTouch: false` (default) | `autoTouch: true` |
+|---|---|---|
+| `check()`/`user()`/`id()` | Read-only | Auto-reseals past halfway |
+| `touch()` | Reseals past halfway | Reseals immediately |
+
+`touch()` preserves original `iat` — `passwordChangedAt` invalidation still works. Does not update user data — use `auth().login(updatedUser)` for that.
 
 #### `attempt()` — Two Modes