@soapjs/soap-auth 1.0.0 → 1.0.1

package/README.md

@@ -15,7 +15,7 @@ npm install @soapjs/soap-auth @soapjs/soap
 ## Requirements
 
 - Node.js 24.17.0 or newer
-- `@soapjs/soap` 0.12 or newer
+- `@soapjs/soap` 0.14 or newer
 
 ## Quick Start
 
@@ -69,6 +69,14 @@ Available recipes:
 
 Recipes are also available from `@soapjs/soap-auth/recipes`.
 
+Type-only subpath imports are supported for TypeScript projects using classic
+`moduleResolution: node`:
+
+```ts
+import type { StorageContext } from "@soapjs/soap-auth/types";
+import type { CookieOptions } from "@soapjs/soap-auth/recipes";
+```
+
 ## Factory Configuration
 
 `SoapAuth.create()` registers built-in strategies from config:
@@ -206,6 +214,26 @@ const auth = await SoapAuth.create({
 
 For providers without a `userinfo` endpoint, implement `user.fetchUser(accessToken)` and return your application user directly.
 
+OAuth2 `state.persistence` and `nonce.persistence` callbacks receive the
+current auth context:
+
+```ts
+state: {
+  persistence: {
+    store: async (state, context, metadata) => {
+      await context.storeInCookie?.(state, { name: metadata?.key ?? "state" });
+    },
+    read: async (context, key) => context.getFromCookie?.(key ?? "state") ?? null,
+    remove: async (context, key) => {
+      await context.removeFromCookie?.(key ?? "state");
+    },
+  },
+}
+```
+
+This lets HTTP adapters such as `soap-express` persist OAuth state and nonce in
+cookies, sessions, or request-scoped storage without global state.
+
 ## Configurable Hybrid OAuth2
 
 Hybrid OAuth2 tries existing JWT/session auth first, then falls back to OAuth2. This is useful when browser users log in through OAuth2 but API clients can keep using JWT.

package/build/services/pkce.service.js

@@ -24,8 +24,9 @@ class PKCEService {
         const cv = this.config.verifier.generate?.() || (0, tools_1.generateRandomString)();
         this.config.verifier.embed(context, cv);
         const expirationTime = Date.now() + (this.config.verifier.expiresIn ?? 300) * 1000;
-        await this.config.verifier.persistence?.store(cv, {
+        await this.config.verifier.persistence?.store(cv, context, {
             expiration: expirationTime,
+            key: "code_verifier",
         });
         return cv;
     }
@@ -37,8 +38,9 @@ class PKCEService {
             this.defaultGenerateCodeChallenge(codeVerifier);
         this.config.challenge.embed(context, challenge);
         const expirationTime = Date.now() + (this.config.challenge.expiresIn ?? 300) * 1000;
-        await this.config.challenge.persistence?.store?.(challenge, {
+        await this.config.challenge.persistence?.store?.(challenge, context, {
             expiration: expirationTime,
+            key: "code_challenge",
         });
         return challenge;
     }
@@ -49,7 +51,7 @@ class PKCEService {
         const codeVerifier = this.extractCodeVerifier(context);
         if (!codeVerifier)
             return true;
-        const stored = await this.config.verifier?.persistence?.read?.(codeVerifier);
+        const stored = await this.config.verifier?.persistence?.read?.(context, codeVerifier);
         if (!stored || !stored.expiration)
             return true;
         return Date.now() > stored.expiration;
@@ -58,7 +60,7 @@ class PKCEService {
         const challenge = this.extractCodeChallenge(context);
         if (!challenge)
             return true;
-        const stored = await this.config.challenge?.persistence?.read?.(challenge);
+        const stored = await this.config.challenge?.persistence?.read?.(context, challenge);
         if (!stored || !stored.expiration)
             return true;
         return Date.now() > stored.expiration;
@@ -66,14 +68,14 @@ class PKCEService {
     async clearCodeVerifier(context) {
         const cv = this.config.verifier.extract(context);
         if (cv) {
-            await this.config.verifier.persistence?.remove?.(cv);
+            await this.config.verifier.persistence?.remove?.(context, cv);
             this.config.verifier.embed(context, "");
         }
     }
     async clearCodeChallenge(context) {
         const challenge = this.config.challenge.extract(context);
         if (challenge) {
-            await this.config.challenge.persistence?.remove?.(challenge);
+            await this.config.challenge.persistence?.remove?.(context, challenge);
             this.config.challenge.embed(context, "");
         }
     }

package/build/strategies/jwt/jwt.strategy.d.ts

@@ -13,8 +13,8 @@ export declare class JwtStrategy<TContext = Soap.HttpContext, TUser extends Soap
     protected verifyRefreshToken(token: string): Promise<any>;
     protected generateAccessToken(user: TUser, context: TContext): Promise<string>;
     protected generateRefreshToken(user: TUser, context: TContext): Promise<string>;
-    protected storeAccessToken(token: string): Promise<void>;
-    protected storeRefreshToken(token: string): Promise<void>;
+    protected storeAccessToken(token: string, context?: TContext): Promise<void>;
+    protected storeRefreshToken(token: string, context?: TContext): Promise<void>;
     protected embedAccessToken(token: string, context: TContext): void;
     protected embedRefreshToken(token: string, context: TContext): void;
     protected extractAccessToken(context: TContext): string | undefined;

package/build/strategies/jwt/jwt.strategy.js

@@ -104,14 +104,14 @@ class JwtStrategy extends token_auth_strategy_1.TokenAuthStrategy {
         const payload = this.buildAccessTokenPayload(user, context);
         return Promise.resolve(jwt_tools_1.JwtTools.generateRefreshToken(payload, this.refreshTokenConfig));
     }
-    async storeAccessToken(token) {
+    async storeAccessToken(token, context) {
         if (this.accessTokenConfig.persistence?.store) {
-            await this.accessTokenConfig.persistence.store(token, null, this.accessTokenConfig.issuer.options.expiresIn);
+            await this.accessTokenConfig.persistence.store(token, context ?? null, { expiresIn: this.accessTokenConfig.issuer.options.expiresIn });
         }
     }
-    async storeRefreshToken(token) {
+    async storeRefreshToken(token, context) {
         if (this.refreshTokenConfig?.persistence?.store) {
-            await this.refreshTokenConfig.persistence.store(token, null, this.refreshTokenConfig.issuer.options.expiresIn);
+            await this.refreshTokenConfig.persistence.store(token, context ?? null, { expiresIn: this.refreshTokenConfig.issuer.options.expiresIn });
         }
     }
     embedAccessToken(token, context) {
@@ -164,7 +164,7 @@ class JwtStrategy extends token_auth_strategy_1.TokenAuthStrategy {
     async invalidateRefreshToken(token, context) {
         const refreshToken = token || (await this.extractRefreshToken(context));
         if (refreshToken) {
-            await this.refreshTokenConfig?.persistence?.remove?.(refreshToken);
+            await this.refreshTokenConfig?.persistence?.remove?.(context ?? null, refreshToken);
             if (context) {
                 jwt_tools_1.JwtTools.clearDefaultJwtCookie(context);
                 jwt_tools_1.JwtTools.clearDefaultJwtHeader(context);
@@ -175,7 +175,7 @@ class JwtStrategy extends token_auth_strategy_1.TokenAuthStrategy {
     async invalidateAccessToken(token, context) {
         const accessToken = token || (await this.extractAccessToken(context));
         if (accessToken) {
-            await this.accessTokenConfig.persistence?.remove?.(accessToken);
+            await this.accessTokenConfig.persistence?.remove?.(context ?? null, accessToken);
             if (context) {
                 jwt_tools_1.JwtTools.clearDefaultJwtCookie(context);
                 jwt_tools_1.JwtTools.clearDefaultJwtHeader(context);

package/build/strategies/oauth2/hybrid.oauth2.strategy.js

@@ -59,7 +59,7 @@ class HybridOAuth2Strategy extends oauth2_strategy_1.OAuth2Strategy {
                 idToken = exchangedTokens.idToken;
             }
             const user = idToken
-                ? await this.verifyIdToken(idToken)
+                ? await this.verifyIdToken(idToken, context)
                 : await this.fetchUser(accessToken);
             if (!user)
                 throw new errors_1.UserNotFoundError();

package/build/strategies/oauth2/oauth2.strategy.d.ts

@@ -55,7 +55,7 @@ export declare abstract class OAuth2Strategy<TContext = Soap.HttpContext, TUser
         idToken?: string;
     }>;
     protected handleTokenRefreshFailure(context: TContext): Promise<void>;
-    protected verifyIdToken(idToken: string): Promise<TUser | null>;
+    protected verifyIdToken(idToken: string, context?: TContext): Promise<TUser | null>;
     revokeToken(token: string): Promise<void>;
     protected isTokenExpired(token: string): boolean;
 }

package/build/strategies/oauth2/oauth2.strategy.js

@@ -161,11 +161,15 @@ class OAuth2Strategy extends base_auth_strategy_1.BaseAuthStrategy {
         let nonce;
         if (this.config.state) {
             state = await oauth2_tools_1.OAuth2Tools.generateState(this.config);
-            await this.config.state.persistence?.store?.(state);
+            await this.config.state.persistence?.store?.(state, context, {
+                key: "state",
+            });
         }
         if (this.config.nonce) {
             nonce = await oauth2_tools_1.OAuth2Tools.generateNonce(this.config);
-            await this.config.nonce.persistence?.store?.(nonce);
+            await this.config.nonce.persistence?.store?.(nonce, context, {
+                key: "nonce",
+            });
         }
         const authUrl = await this.buildAuthorizationUrl(context, state, nonce);
         this.redirectUser(context, authUrl);
@@ -175,14 +179,14 @@ class OAuth2Strategy extends base_auth_strategy_1.BaseAuthStrategy {
             return;
         }
         const returnedState = oauth2_tools_1.OAuth2Tools.extractState(context);
-        const storedState = (await this.config.state.persistence?.read?.());
+        const storedState = (await this.config.state.persistence?.read?.(context, "state"));
         const valid = this.config.state.validateState
             ? await this.config.state.validateState(storedState, returnedState)
             : !!storedState && storedState === returnedState;
         if (!valid) {
             throw new oauth2_errors_1.InvalidStateError();
         }
-        await this.config.state.persistence?.remove?.();
+        await this.config.state.persistence?.remove?.(context, "state");
     }
     async buildAuthorizationUrl(context, state, nonce) {
         const params = new URLSearchParams({
@@ -363,8 +367,8 @@ class OAuth2Strategy extends base_auth_strategy_1.BaseAuthStrategy {
             this.logger?.error(e);
         }
     }
-    async verifyIdToken(idToken) {
-        const storedNonce = await this.config?.nonce?.persistence?.read?.();
+    async verifyIdToken(idToken, context) {
+        const storedNonce = await this.config?.nonce?.persistence?.read?.(context, "nonce");
         if (storedNonce) {
             const decodedToken = await this.jwks.verify(idToken);
             if (decodedToken.nonce) {

package/build/strategies/oauth2/oauth2.types.d.ts

@@ -9,13 +9,13 @@ export interface OAuth2Endpoints {
     logoutUrl?: string;
 }
 export interface OAuth2StateConfig<TContext = unknown, TData = any> {
-    persistence?: PersistenceConfig;
+    persistence?: PersistenceConfig<TData, TContext>;
     context?: ContextOperationConfig<TContext, TData>;
     generateState?: () => string | Promise<string>;
     validateState?: (storedState: TContext, returnedState: string) => boolean | Promise<boolean>;
 }
 export interface OAuth2NonceConfig<TContext = unknown, TData = any> {
-    persistence?: PersistenceConfig;
+    persistence?: PersistenceConfig<TData, TContext>;
     context?: ContextOperationConfig<TContext, TData>;
     generateNonce?: () => string | Promise<string>;
     validateNonce?: (storedNonce: string | null, returnedNonce: string) => boolean | Promise<boolean>;
@@ -47,7 +47,7 @@ export interface OAuth2StrategyConfig<TContext = unknown, TUser = unknown> exten
         [key: string]: AuthRouteConfig;
     };
     state?: OAuth2StateConfig<TContext>;
-    nonce?: OAuth2NonceConfig;
+    nonce?: OAuth2NonceConfig<TContext>;
     jwks?: JwksConfig;
 }
 export interface OAuth2ProviderConfig<TContext = unknown, TUser = unknown> extends Omit<OAuth2StrategyConfig<TContext, TUser>, "endpoints" | "grantType" | "routes"> {

package/build/strategies/token-auth.strategy.d.ts

@@ -13,8 +13,8 @@ export declare abstract class TokenAuthStrategy<TContext = Soap.HttpContext, TUs
     protected abstract verifyRefreshToken(token: string): Promise<any>;
     protected abstract generateAccessToken(data: TUser, context: TContext): Promise<string>;
     protected abstract generateRefreshToken(data: TUser, context: TContext): Promise<string>;
-    protected abstract storeAccessToken(token: string): Promise<void>;
-    protected abstract storeRefreshToken(token: string): Promise<void>;
+    protected abstract storeAccessToken(token: string, context?: TContext): Promise<void>;
+    protected abstract storeRefreshToken(token: string, context?: TContext): Promise<void>;
     protected abstract invalidateAccessToken(token: string, context?: TContext): Promise<void>;
     protected abstract invalidateRefreshToken(token: string, context?: TContext): Promise<void>;
     protected abstract embedAccessToken(token: string, context: TContext): void;

package/build/strategies/token-auth.strategy.js

@@ -153,10 +153,10 @@ class TokenAuthStrategy extends base_auth_strategy_1.BaseAuthStrategy {
                     refreshToken = await this.generateRefreshToken(user, context);
                 }
             }
-            await this.storeAccessToken(accessToken);
+            await this.storeAccessToken(accessToken, context);
             this.embedAccessToken(accessToken, context);
             if (refreshToken) {
-                await this.storeRefreshToken(refreshToken);
+                await this.storeRefreshToken(refreshToken, context);
                 this.embedRefreshToken(refreshToken, context);
             }
             this.logger?.info(`JWT issued successfully`);

package/build/types.d.ts

@@ -1,6 +1,6 @@
 import * as Soap from "@soapjs/soap";
 export type AuthResult<TUser extends Soap.AuthUser = Soap.AuthUser> = Soap.AuthResult<TUser>;
-export type AuthStrategy<TUser extends Soap.AuthUser = Soap.AuthUser> = Soap.AuthStrategy<TUser>;
+export type AuthStrategy<TUser extends Soap.AuthUser = Soap.AuthUser, TContext extends Soap.HttpContext = Soap.HttpContext> = Soap.AuthStrategy<TUser, TContext>;
 import { LocalStrategyConfig } from "./strategies/local/local.types";
 import { OAuth2ProviderConfig } from "./strategies/oauth2/oauth2.types";
 import { ApiKeyStrategyConfig } from "./strategies/api-key/api-key.types";
@@ -75,13 +75,13 @@ export interface MfaConfig<TUser = unknown, TContext = unknown> {
 }
 export type PasswordType = "default" | "one-time" | "temporary";
 export type NewPasswordOptions = {
-    expiresIn?: number;
+    expiresIn?: string | number;
     type: PasswordType;
     additional?: Record<string, unknown>;
 };
 export type PasswordInfo = {
     type: PasswordType;
-    expiresIn?: number;
+    expiresIn?: string | number;
     lastChangeDate?: Date;
 };
 export interface PasswordPolicyConfig {
@@ -259,10 +259,17 @@ export interface TokenVerifierConfig {
     };
     verify?: (token: string) => Promise<any>;
 }
-export interface PersistenceConfig<T = any> {
-    store: (data: any, ...args: any[]) => Promise<void>;
-    read: (...args: any[]) => Promise<T | null>;
-    remove: (...args: any[]) => Promise<void>;
+export interface PersistenceMetadata {
+    key?: string;
+    name?: string;
+    expiration?: number;
+    expiresIn?: string | number;
+    [key: string]: unknown;
+}
+export interface PersistenceConfig<T = any, TContext = any> {
+    store: (data: any, context?: TContext | null, metadata?: PersistenceMetadata, ...args: any[]) => Promise<void> | void;
+    read: (context?: TContext | null, key?: string, ...args: any[]) => Promise<T | null> | T | null;
+    remove: (context?: TContext | null, key?: string, ...args: any[]) => Promise<void> | void;
 }
 export interface ContextOperationConfig<TContext = any, TData = any> {
     embed?: (context: TContext, data: TData) => void;
@@ -272,7 +279,7 @@ export interface TokenConfig<TContext = any, TUser = any> extends ContextOperati
     rotation?: TokenRotationConfig<TContext, TUser>;
     issuer?: TokenIssuerConfig<TContext>;
     verifier?: TokenVerifierConfig;
-    persistence?: PersistenceConfig;
+    persistence?: PersistenceConfig<string, TContext>;
     additional?: Record<string, unknown>;
 }
 export interface RefreshTokenConfig<TContext = any, TUser = any> extends TokenConfig<TContext, TUser> {
@@ -298,13 +305,13 @@ export interface PKCEConfig<TContext> {
         generate?: (codeVerifier: string) => string;
         embed?: (context: TContext, challenge: string) => void;
         extract?: (context: TContext) => string | null;
-        persistence?: PersistenceConfig;
+        persistence?: PersistenceConfig<any, TContext>;
     };
     verifier: {
         expiresIn?: number;
         generate?: () => string;
         embed?: (context: TContext, codeVerifier: string) => void;
         extract?: (context: TContext) => string | null;
-        persistence?: PersistenceConfig;
+        persistence?: PersistenceConfig<any, TContext>;
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soapjs/soap-auth",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Authentication strategies, sessions, MFA, and token helpers for the SoapJS ecosystem.",
   "homepage": "https://docs.soapjs.com",
   "repository": {
@@ -72,6 +72,52 @@
     },
     "./package.json": "./package.json"
   },
+  "typesVersions": {
+    "*": {
+      "session": [
+        "./build/session/index.d.ts"
+      ],
+      "session/*": [
+        "./build/session/*"
+      ],
+      "services": [
+        "./build/services/index.d.ts"
+      ],
+      "services/*": [
+        "./build/services/*"
+      ],
+      "strategies": [
+        "./build/strategies/index.d.ts"
+      ],
+      "strategies/*": [
+        "./build/strategies/*"
+      ],
+      "tools": [
+        "./build/tools/index.d.ts"
+      ],
+      "tools/*": [
+        "./build/tools/*"
+      ],
+      "recipes": [
+        "./build/recipes/index.d.ts"
+      ],
+      "recipes/*": [
+        "./build/recipes/*"
+      ],
+      "errors": [
+        "./build/errors.d.ts"
+      ],
+      "types": [
+        "./build/types.d.ts"
+      ],
+      "soap-auth": [
+        "./build/soap-auth.d.ts"
+      ],
+      "utils/validation": [
+        "./build/utils/validation.d.ts"
+      ]
+    }
+  },
   "files": [
     "build",
     "README.md",
@@ -93,14 +139,14 @@
     "access": "public"
   },
   "devDependencies": {
-    "@soapjs/soap": "^0.12.1",
+    "@soapjs/soap": "^0.14.0",
     "@types/jest": "^29.5.14",
     "jest": "^29.7.0",
     "ts-jest": "^29.4.11",
     "typescript": "^4.8.2"
   },
   "peerDependencies": {
-    "@soapjs/soap": ">=0.12.0"
+    "@soapjs/soap": ">=0.14.0"
   },
   "engines": {
     "node": ">=24.17.0"