@clocklobster/cognito-client 1.0.0 → 1.1.0

package/dist/index.d.ts

@@ -112,6 +112,15 @@ export interface CognitoClientOptions {
     /** Current page path + query, used to build the `?returnTo=` destination. */
     getCurrentPath?: () => string;
 }
+/**
+ * Fail-closed JWT expiry probe (no signature verification — cryptographic
+ * validation belongs to the backend and the Cognito SDK; this is purely a
+ * render-gating heuristic so a dead token never passes a page-load guard).
+ *
+ * Returns true when the token is expired OR cannot be parsed / carries no
+ * numeric `exp` claim. Real Cognito id tokens always carry `exp`.
+ */
+export declare function isTokenExpired(token: string, nowMs?: number): boolean;
 export declare class CognitoClient {
     private readonly options;
     private pool;
@@ -146,6 +155,19 @@ export declare class CognitoClient {
      */
     completeNewPassword(newPassword: string, userAttributes?: Record<string, unknown>): Promise<SessionTokens>;
     getSession(): Promise<RestoredSession | null>;
+    /**
+     * Canonical async page-load gate for protected pages.
+     *
+     * Unlike a sync token-presence check (which passes with a stale-but-cached
+     * token after credentials timeout, letting the page fetch and render
+     * private data before the 401 path discovers the dead session), this
+     * validates the session through the SDK: a live session is returned
+     * (refreshing via the stored refresh token when the id token expired but
+     * the refresh token is still alive — seamless, no redirect), while a truly
+     * dead session resolves null AND redirects to `loginUrl` immediately —
+     * before any API fetch fires. Never throws.
+     */
+    ensureSession(loginUrl: string): Promise<RestoredSession | null>;
     refreshSession(): Promise<SessionTokens>;
     forgotPassword(email: string): Promise<void>;
     confirmNewPassword(email: string, code: string, newPassword: string): Promise<void>;

package/dist/index.js

@@ -28,6 +28,30 @@
 function resolvePoolConfig(value) {
     return typeof value === 'function' ? value() : value;
 }
+/** Clock skew (seconds) tolerated when judging a JWT expired. */
+const TOKEN_EXPIRY_SKEW_SEC = 60;
+/**
+ * Fail-closed JWT expiry probe (no signature verification — cryptographic
+ * validation belongs to the backend and the Cognito SDK; this is purely a
+ * render-gating heuristic so a dead token never passes a page-load guard).
+ *
+ * Returns true when the token is expired OR cannot be parsed / carries no
+ * numeric `exp` claim. Real Cognito id tokens always carry `exp`.
+ */
+export function isTokenExpired(token, nowMs = Date.now()) {
+    try {
+        const parts = token.split('.');
+        if (parts.length < 2)
+            return true;
+        const payload = JSON.parse(atob(parts[1].replace(/-/g, '+').replace(/_/g, '/')));
+        if (typeof payload.exp !== 'number' || !Number.isFinite(payload.exp))
+            return true;
+        return payload.exp * 1000 <= nowMs + TOKEN_EXPIRY_SKEW_SEC * 1000;
+    }
+    catch {
+        return true;
+    }
+}
 export class CognitoClient {
     constructor(options) {
         this.options = options;
@@ -190,6 +214,30 @@ export class CognitoClient {
             }
         });
     }
+    /**
+     * Canonical async page-load gate for protected pages.
+     *
+     * Unlike a sync token-presence check (which passes with a stale-but-cached
+     * token after credentials timeout, letting the page fetch and render
+     * private data before the 401 path discovers the dead session), this
+     * validates the session through the SDK: a live session is returned
+     * (refreshing via the stored refresh token when the id token expired but
+     * the refresh token is still alive — seamless, no redirect), while a truly
+     * dead session resolves null AND redirects to `loginUrl` immediately —
+     * before any API fetch fires. Never throws.
+     */
+    async ensureSession(loginUrl) {
+        try {
+            const session = await this.getSession();
+            if (!session)
+                this.redirectToLogin(loginUrl);
+            return session;
+        }
+        catch {
+            this.redirectToLogin(loginUrl);
+            return null;
+        }
+    }
     refreshSession() {
         this.initPool();
         const cognitoUser = this.pool.getCurrentUser();
@@ -203,6 +251,10 @@ export class CognitoClient {
         return new Promise((resolve, reject) => {
             cognitoUser.getSession((err, session) => {
                 if (err || !session || !session.isValid()) {
+                    // Terminal failure — same cleanup as getSession: a stale/invalid
+                    // cached session must not leave token state behind.
+                    cognitoUser.signOut();
+                    this.clearTokens();
                     return reject(err ? this.options.errorMapper(err) : new Error('No valid cached session'));
                 }
                 this.setTokensFromSession(session, cognitoUser.getUsername());

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Generic, dependency-injected browser AWS Cognito client — sign-up, sign-in, session restore/refresh, NEW_PASSWORD_REQUIRED challenge, forgot/reset password",
   "license": "MIT",
   "author": "Victor Salmon",
@@ -15,6 +15,7 @@
   "bugs": {
     "url": "https://github.com/victorsalmon/cognito-client/issues"
   },
+  "packageManager": "pnpm@11.22.0",
   "keywords": [
     "aws",
     "cognito",
@@ -37,9 +38,14 @@
     "build": "tsc -p tsconfig.build.json",
     "postinstall": "tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run"
+    "test": "vitest run",
+    "test:property": "vitest run property",
+    "test:mutation": "stryker run"
   },
   "devDependencies": {
+    "@stryker-mutator/core": "^10.0.0",
+    "@stryker-mutator/vitest-runner": "^10.0.0",
+    "fast-check": "^4.9.0",
     "jsdom": "^26.0.0",
     "typescript": "^5.7.2",
     "vitest": "^3.2.7"