ideal-auth 1.1.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
 

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,14 +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: config.session?.autoTouch ?? false,
+        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/types.d.ts

@@ -78,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;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ideal-auth",
-  "version": "1.1.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
 
@@ -169,9 +174,9 @@ type LoginOptions = {
 
 #### Session Extension
 
-Two options for keeping active users logged in:
+Three ways to extend sessions for active users:
 
-**`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).
+**Global `autoTouch`** — config level. For Express, Hono, Elysia, SvelteKit where every route can write cookies:
 
 ```typescript
 const auth = createAuth<User>({
@@ -180,7 +185,19 @@ const auth = createAuth<User>({
 });
 ```
 
-**Manual `touch()`** — call in middleware. When `autoTouch` is false (default), only reseals past halfway. When `autoTouch` is true, reseals immediately.
+**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
 const session = auth();