ideal-auth 1.0.0 → 1.2.0

package/README.md

@@ -88,7 +88,12 @@ await session.logout();
 
 ### `createAuth(config)`
 
-Returns a function `auth()` that creates an `AuthInstance` on each call.
+Returns a function `auth(options?)` that creates an `AuthInstance` on each call. Pass `{ autoTouch: true }` to enable automatic session extension for that request.
+
+```typescript
+const session = auth();                      // default — read-only check/user/id
+const session = auth({ autoTouch: true });   // auto-extends session past halfway on check/user/id
+```
 
 #### Config
 
@@ -106,6 +111,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 +122,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.d.ts

@@ -1,4 +1,4 @@
-import type { AnyUser, AuthInstance, AuthConfig } from './types';
+import type { AnyUser, AuthInstance, AuthConfig, AuthFactoryOptions } from './types';
 /**
  * Create an auth factory.
  *
@@ -9,4 +9,4 @@ import type { AnyUser, AuthInstance, AuthConfig } from './types';
  * type SessionUser = { id: string; email: string; name: string };
  * createAuth<SessionUser>({ ... })
  */
-export declare function createAuth<TUser extends AnyUser>(config: AuthConfig<TUser>): () => AuthInstance<TUser>;
+export declare function createAuth<TUser extends AnyUser>(config: AuthConfig<TUser>): (options?: AuthFactoryOptions) => AuthInstance<TUser>;

package/dist/auth.js

@@ -27,13 +27,15 @@ export function createAuth(config) {
     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({
+    const configAutoTouch = config.session?.autoTouch ?? false;
+    return (options) => createAuthInstance({
         secret: config.secret,
         cookie: config.cookie,
         cookieName: config.session?.cookieName ?? SESSION_DEFAULTS.cookieName,
         maxAge: config.session?.maxAge ?? SESSION_DEFAULTS.maxAge,
         rememberMaxAge: config.session?.rememberMaxAge ?? SESSION_DEFAULTS.rememberMaxAge,
         cookieOptions: config.session?.cookie ?? {},
+        autoTouch: options?.autoTouch ?? configAutoTouch,
         resolveUser: config.resolveUser,
         sessionFields: config.sessionFields,
         hash: config.hash,

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, AuthConfigWithResolveUser, AuthConfigWithSessionFields, 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, AuthFactoryOptions, HashInstance, TokenVerifierConfig, TokenVerifierInstance, RateLimitStore, RateLimiterConfig, RateLimitResult, TOTPConfig, TOTPInstance, RecoveryCodeResult, } from './types';

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>;
@@ -75,6 +78,10 @@ export interface AuthConfigWithSessionFields<TUser extends AnyUser, K extends ke
     sessionFields: K[];
 }
 export type AuthConfig<TUser extends AnyUser = AnyUser> = AuthConfigWithResolveUser<TUser> | AuthConfigWithSessionFields<TUser>;
+export interface AuthFactoryOptions {
+    /** Override autoTouch for this request. When true, check()/user()/id() auto-extend the session past the halfway point. */
+    autoTouch?: boolean;
+}
 export interface HashConfig {
     rounds?: number;
 }
@@ -86,7 +93,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.2.0",
   "description": "Auth primitives for the JS ecosystem. Zero framework dependencies.",
   "scripts": {
     "build": "tsc",

package/skills/ideal-auth/SKILL.md

@@ -64,9 +64,14 @@ Generate encryption key: `bunx ideal-auth encryption-key` (for encrypting TOTP s
 
 ## API Reference
 
-### `createAuth(config): () => AuthInstance`
+### `createAuth(config): (options?) => AuthInstance`
 
-Returns a factory function. Call `auth()` per request to get an `AuthInstance` scoped to that request's cookies. The instance caches the session payload and user — call it once per request and reuse.
+Returns a factory function. Call `auth()` per request to get an `AuthInstance` scoped to that request's cookies. Pass `{ autoTouch: true }` to enable automatic session extension for that request. The instance caches the session payload and user — call it once per request and reuse.
+
+```typescript
+const session = auth();                      // read-only check/user/id
+const session = auth({ autoTouch: true });   // auto-extends past halfway on check/user/id
+```
 
 #### AuthConfig
 
@@ -167,19 +172,46 @@ type LoginOptions = {
 };
 ```
 
-#### Session Extension with `touch()`
+#### Session Extension
 
-Sessions have a fixed expiry. Call `touch()` in middleware to extend the session for active users:
+Three ways to extend sessions for active users:
+
+**Global `autoTouch`** — config level. For Express, Hono, Elysia, SvelteKit where every route can write cookies:
+
+```typescript
+const auth = createAuth<User>({
+  session: { autoTouch: true },
+  ...
+});
+```
+
+**Per-request `autoTouch`** — pass when calling `auth()`. Ideal for Next.js where middleware can write cookies but Server Components can't:
+
+```typescript
+// Next.js middleware — autoTouch for this request only
+const session = auth({ autoTouch: true });
+await session.check(); // auto-extends past halfway
+
+// Next.js Server Component — default, read-only
+const session = auth();
+await session.check(); // no cookie writes
+```
+
+**Manual `touch()`** — explicit 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