@seamless-auth/express 0.0.0 → 0.0.1-beta.3

package/README.md

@@ -1,13 +1,268 @@
 # @seamless-auth/server-express
 
-Drop-in Express adapter for Seamless Auth “server mode” authentication.
+### Seamless Auth Express Adapter
 
-```js
+A secure, passwordless **server-side adapter** that connects your Express API to a private Seamless Auth Server.
+
+It proxies all authentication flows, manages signed cookies, and gives you out-of-the-box middleware for verifying users and enforcing roles.
+
+> **npm:** https://www.npmjs.com/package/@seamless-auth/express  
+> **Docs:** https://docs.seamlessauth.com  
+> **Repo:** https://github.com/fells-code/seamless-auth-server
+
+> Couple with https://github.com/fells-code/seamless-auth/react for an end to end seamless experience
+
+> Or get a full starter application with https://github.com/fells-code/create-seamless
+
+---
+
+---
+
+## Installation
+
+```bash
+npm install @seamless-auth/server-express
+# or
+yarn add @seamless-auth/server-express
+```
+
+## Quick Example
+
+```ts
 import express from "express";
-import createSeamlessAuthServer from "@seamless-auth/server-express";
+import cookieParser from "cookie-parser";
+import createSeamlessAuthServer, {
+  requireAuth,
+  requireRole,
+} from "@seamless-auth/server-express";
 
 const app = express();
-app.use("/auth", createSeamlessAuthServer({
-  authServerUrl: process.env.AUTH_SERVER_URL,
-  cookieDomain: ".myapp.com"
-}));
+app.use(cookieParser());
+
+// Public Seamless Auth endpoints
+app.use(
+  "/auth",
+  createSeamlessAuthServer({ authServerUrl: process.env.AUTH_SERVER_URL! })
+);
+
+// Everything after this line requires authentication
+app.use(requireAuth());
+
+app.get("/api/me", (req, res) => res.json({ user: (req as any).user }));
+app.get("/admin", requireRole("admin"), (req, res) =>
+  res.json({ message: "Welcome admin!" })
+);
+
+app.listen(5000, () => console.log("Portal API running on :5000"));
+```
+
+---
+
+# Full Documentation
+
+## Overview
+
+`@seamless-auth/express` lets your backend API act as an authentication and authorization server using Seamless Auth.
+
+It transparently proxies and validates authentication flows so your frontend can use a single API endpoint for:
+
+- Login / Registration / Logout
+- User introspection (`/auth/me`)
+- Session cookies (signed JWTs)
+- Role & permission guards
+- Internal Auth Server communication (JWKS + service tokens)
+
+Everything happens securely between your API and a private Seamless Auth Server.
+
+---
+
+## Architecture
+
+```
+[Frontend App]
+     │
+     ▼
+[Your Express API]
+   ├─ createSeamlessAuthServer()  ← mounts /auth routes
+   ├─ requireAuth()               ← verifies signed cookie JWT
+   ├─ requireRole('admin')        ← role-based guard
+   └─ getSeamlessUser()           ← calls Auth Server
+     │
+     ▼
+[Private Seamless Auth Server]
+```
+
+---
+
+## Environment Variables
+
+| Variable                      | Description                            | Example                   |
+| ----------------------------- | -------------------------------------- | ------------------------- |
+| `AUTH_SERVER_URL`             | Base URL of your Seamless Auth Server  | `https://auth.client.com` |
+| `SEAMLESS_COOKIE_SIGNING_KEY` | Secret key for signing JWT cookies     | `base64:...`              |
+| `SEAMLESS_SERVICE_TOKEN`      | Private key for API → Auth Server JWTs | RSA PEM                   |
+| `SERVICE_JWT_KEYID`           | Key ID for JWKS                        | `service-main`            |
+| `COOKIE_DOMAIN`               | Domain for cookies                     | `.client.com`             |
+
+---
+
+## API Reference
+
+### `createSeamlessAuthServer(options)`
+
+Mounts an Express router exposing the full Seamless Auth flow:
+
+- `/auth/login/start`
+- `/auth/login/finish`
+- `/auth/webauthn/...`
+- `/auth/registration/...`
+- `/auth/me`
+- `/auth/logout`
+
+**Options**
+
+```ts
+{
+  authServerUrl: string;        // required
+  cookieDomain?: string;
+  cookieNameOverrides?: {
+    preauth?: string;
+    registration?: string;
+    access?: string;
+  };
+}
+```
+
+---
+
+### `requireAuth(cookieName?: string)`
+
+Middleware that validates the signed access cookie (`seamless_auth_access` by default)  
+and attaches the decoded user payload to `req.user`.
+
+```ts
+app.get("/api/profile", requireAuth(), (req, res) => {
+  res.json({ user: req.user });
+});
+```
+
+---
+
+### `requireRole(role: string, cookieName?: string)`
+
+Role-based authorization guard.  
+Blocks non-matching roles with HTTP 403.
+
+```ts
+app.get("/admin", requireRole("admin"), (req, res) => {
+  res.json({ message: "Welcome admin!" });
+});
+```
+
+---
+
+### `getSeamlessUser(req, authServerUrl, cookieName?)`
+
+Calls the Auth Server’s `/internal/session/introspect` endpoint using a signed service JWT  
+and returns the Seamless user object.
+
+```ts
+const user = await getSeamlessUser(req, process.env.AUTH_SERVER_URL!);
+```
+
+User shape
+
+```ts
+{
+  id: string;
+  email: string;
+  phone: string;
+  roles: string[]
+}
+```
+
+## End-to-End Flow
+
+1. **Frontend** → `/auth/login/start`  
+   → API proxies to Seamless Auth Server  
+   → sets short-lived pre-auth cookie.
+
+2. **Frontend** → `/auth/webauthn/finish`  
+   → API proxies, validates, sets access cookie (`seamless_auth_access`).
+
+3. **Subsequent API calls** → `/api/...`  
+   → `requireAuth()` verifies cookie and attaches user.  
+   → Role routes use `requireRole()`.
+
+---
+
+## Local Development
+
+In order to develop with your Seamless Auth server instance, you will need to have:
+
+- Created an account @ https://dashboard.seamlessauth.com
+- Created a new Seamless Auth application
+
+Example env:
+
+```bash
+AUTH_SERVER_URL=http://https://<identifier>.seamlessauth.com # Found in the portal
+COOKIE_DOMAIN=localhost # Or frontend domain in prod
+SEAMLESS_COOKIE_SIGNING_KEY=local-secret-key # Found in the portal
+```
+
+---
+
+## Example Middleware Stack
+
+```ts
+const AUTH_SERVER_URL = process.env.AUTH_SERVER_URL!;
+app.use(cors({ origin: "https://localhost:5001", credentials: true }));
+app.use(express.json());
+app.use(cookieParser());
+app.use("/auth", createSeamlessAuthServer({ authServerUrl: AUTH_SERVER_URL }));
+app.use(requireAuth());
+```
+
+---
+
+## Security Model
+
+| Layer                 | Auth Mechanism                        | Signed By          |
+| --------------------- | ------------------------------------- | ------------------ |
+| **Frontend ↔ API**    | Signed JWT in HttpOnly cookie (HS256) | Client API         |
+| **API ↔ Auth Server** | Bearer Service JWT (RS256)            | API’s private key  |
+| **Auth Server**       | Validates service tokens via JWKS     | Seamless Auth JWKS |
+
+All tokens and cookies are stateless and cryptographically verifiable.
+
+---
+
+## Testing
+
+You can mock `requireAuth` and test Express routes via `supertest`.
+
+Example:
+
+```ts
+import { requireAuth } from "@seamless-auth/server-express";
+app.get("/api/test", requireAuth(), (req, res) => res.json({ ok: true }));
+```
+
+---
+
+## Roadmap
+
+| Feature                                      | Status      |
+| -------------------------------------------- | ----------- |
+| JWKS-verified response signing               | ✅          |
+| OIDC discovery & SSO readiness               | planned     |
+| Federation (Google / Okta)                   | future      |
+| Multi-framework adapters (Next.js / Fastify) | coming soon |
+
+---
+
+## License
+
+MIT © 2025 Fells Code LLC  
+Part of the **Seamless Auth** ecosystem.

package/dist/createServer.js

@@ -8,10 +8,13 @@ export function createSeamlessAuthServer(opts) {
     const r = express.Router();
     r.use(express.json());
     r.use(cookieParser());
-    const { authServerUrl, cookieDomain = "", accesscookieName = "seamless-auth-access", registrationCookieName = "seamless-auth-registration", refreshCookieName = "seamless-auth-refresh", preAuthCookieName = "seamless-auth-pre-auth" } = opts;
+    const { authServerUrl, cookieDomain = "", accesscookieName = "seamless-access", registrationCookieName = "seamless-ephemeral", refreshCookieName = "seamless-refresh", preAuthCookieName = "seamless-ephemeral", } = opts;
     const proxy = (path, method = "POST") => async (req, res) => {
         try {
-            const response = await authFetch(req, `${authServerUrl}/${path}`, { method, body: req.body });
+            const response = await authFetch(req, `${authServerUrl}/${path}`, {
+                method,
+                body: req.body,
+            });
             res.status(response.status).json(await response.json());
         }
         catch (error) {
@@ -24,7 +27,7 @@ export function createSeamlessAuthServer(opts) {
         accesscookieName,
         registrationCookieName,
         refreshCookieName,
-        preAuthCookieName
+        preAuthCookieName,
     }));
     r.post("/webAuthn/login/start", proxy("webAuthn/login/start"));
     r.post("/webAuthn/login/finish", finishLogin);
@@ -33,9 +36,10 @@ export function createSeamlessAuthServer(opts) {
     r.post("/otp/verify-phone-otp", proxy("otp/verify-phone-otp"));
     r.post("/otp/verify-email-otp", proxy("otp/verify-email-otp"));
     r.post("/login", login);
+    r.post("/users/update", proxy("users/update"));
     r.post("/registration/register", register);
-    r.post("/logout", logout);
     r.get("/users/me", me);
+    r.get("/logout", logout);
     return r;
     async function login(req, res) {
         const up = await authFetch(req, `${authServerUrl}/login`, {
@@ -75,15 +79,14 @@ export function createSeamlessAuthServer(opts) {
         if (!up.ok)
             return res.status(up.status).json(data);
         const verifiedAccessToken = await verifySignedAuthResponse(data.token, authServerUrl);
-        const verifiedRefreshToken = await verifySignedAuthResponse(data.refreshToken, authServerUrl);
-        if (!verifiedAccessToken || !verifiedRefreshToken) {
+        if (!verifiedAccessToken) {
             throw new Error("Invalid signed response from Auth Server");
         }
-        if (verifiedAccessToken.sub !== data.sub || verifiedRefreshToken.sub !== data.sub) {
+        if (verifiedAccessToken.sub !== data.sub) {
             throw new Error("Signature mismatch with data payload");
         }
         setSessionCookie(res, { sub: data.sub, roles: data.roles }, cookieDomain, data.ttl, accesscookieName);
-        setSessionCookie(res, { sub: data.sub, refreshToken: data.refreshToken }, cookieDomain, data.ttl, refreshCookieName);
+        setSessionCookie(res, { sub: data.sub, refreshToken: data.refreshToken }, req.hostname, data.refreshTtl, refreshCookieName);
         res.status(200).json(data).end();
     }
     async function finishRegister(req, res) {
@@ -98,12 +101,9 @@ export function createSeamlessAuthServer(opts) {
         res.status(204).end();
     }
     async function logout(req, res) {
-        const sid = req.cookies[accesscookieName];
-        if (sid)
-            await authFetch(req, `${authServerUrl}/logout`, {
-                method: "POST",
-                body: { sid },
-            });
+        await authFetch(req, `${authServerUrl}/logout`, {
+            method: "GET",
+        });
         clearAllCookies(res, cookieDomain, accesscookieName, registrationCookieName, refreshCookieName);
         res.status(204).end();
     }
@@ -112,14 +112,6 @@ export function createSeamlessAuthServer(opts) {
             method: "GET",
         });
         const data = (await up.json());
-        console.log(data.token);
-        const verified = await verifySignedAuthResponse(data.token, authServerUrl);
-        if (!verified) {
-            throw new Error("Invalid signed response from Auth Server");
-        }
-        if (verified.sub !== data.sub) {
-            throw new Error("Signature mismatch with data payload");
-        }
         clearSessionCookie(res, cookieDomain, preAuthCookieName);
         if (!data.user)
             return res.status(401).json({ error: "unauthenticated" });

package/dist/internal/authFetch.d.ts

@@ -5,4 +5,4 @@ export interface AuthFetchOptions {
     cookies?: string[];
     headers?: Record<string, string>;
 }
-export declare function authFetch(req: CookieRequest, url: string, { method, body, cookies, headers }?: AuthFetchOptions): Promise<import("node-fetch").Response>;
+export declare function authFetch(req: CookieRequest, url: string, { method, body, cookies, headers }?: AuthFetchOptions): Promise<Response>;

package/dist/internal/authFetch.js

@@ -1,20 +1,28 @@
-import fetch from "node-fetch";
 import jwt from "jsonwebtoken";
-const privateKey = process.env.SERVICE_JWT_KEY;
+const serviceKey = process.env.SEAMLESS_SERVICE_TOKEN;
 export async function authFetch(req, url, { method = "POST", body, cookies, headers = {} } = {}) {
-    const token = privateKey
-        ? jwt.sign({ aud: "auth-internal", iss: "portal-api", sub: req.cookiePayload?.sub, role: req.cookiePayload?.roles }, privateKey, {
-            expiresIn: "60s",
-            keyid: "service-main",
-        })
-        : undefined;
-    if (!token) {
-        throw new Error("Cannot sign JWT for communications with Seamless Auth Server. Did you set your SERVICE_JWT_KEY?");
+    if (!serviceKey) {
+        throw new Error("Cannot sign service token. Missing SEAMLESS_SERVICE_TOKEN");
     }
+    // -------------------------------
+    // Issue short-lived machine token
+    // -------------------------------
+    const token = jwt.sign({
+        // Minimal, safe fields
+        iss: process.env.FRONTEND_URL,
+        aud: process.env.AUTH_SERVER,
+        sub: req.cookiePayload?.sub,
+        roles: req.cookiePayload?.roles ?? [],
+        iat: Math.floor(Date.now() / 1000),
+    }, serviceKey, {
+        expiresIn: "60s", // Short-lived = safer
+        algorithm: "HS256", // HMAC-based
+        keyid: "dev-main", // For future rotation
+    });
     const finalHeaders = {
         ...(method !== "GET" && { "Content-Type": "application/json" }),
         ...(cookies ? { Cookie: cookies.join("; ") } : {}),
-        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        Authorization: `Bearer ${token}`,
         ...headers,
     };
     let finalUrl = url;

package/dist/internal/cookie.d.ts

@@ -1,6 +1,7 @@
 import { Response } from "express";
 export interface CookiePayload {
     sub: string;
+    token?: string;
     refreshToken?: string;
     roles?: string[];
 }

package/dist/internal/cookie.js

@@ -6,12 +6,12 @@ if (!COOKIE_SECRET) {
 export function setSessionCookie(res, payload, domain, ttlSeconds = 300, name = "sa_session") {
     const token = jwt.sign(payload, COOKIE_SECRET, {
         algorithm: "HS256",
-        expiresIn: ttlSeconds,
+        expiresIn: `${ttlSeconds}s`,
     });
     res.cookie(name, token, {
         httpOnly: true,
-        secure: true,
-        sameSite: "lax",
+        secure: process.env.NODE_ENV === "production",
+        sameSite: process.env.NODE_ENV === "production" ? "none" : "lax",
         path: "/",
         domain,
         maxAge: ttlSeconds * 1000,

package/dist/internal/getSeamlessUser.d.ts

@@ -1,4 +1,4 @@
-import type { Request } from "express";
+import { CookieRequest } from "../middleware/ensureCookies.js";
 /**
  * Retrieves the Seamless Auth user information by calling the auth server's introspection endpoint.
  * Requires the sa_session (or custom) cookie to be present on the request.
@@ -7,4 +7,4 @@ import type { Request } from "express";
  * @param authServerUrl Base URL of the client's auth server
  * @returns The user data object if valid, or null if invalid/unauthenticated
  */
-export declare function getSeamlessUser<T = any>(req: Request, authServerUrl: string): Promise<T | null>;
+export declare function getSeamlessUser<T = any>(req: CookieRequest, authServerUrl: string, cookieName?: string): Promise<T | null>;

package/dist/internal/getSeamlessUser.js

@@ -1,5 +1,5 @@
 import { authFetch } from "./authFetch.js";
-import { verifySignedAuthResponse } from "./verifySignedAuthResponse.js";
+import { verifyCookieJwt } from "./verifyCookieJwt.js";
 /**
  * Retrieves the Seamless Auth user information by calling the auth server's introspection endpoint.
  * Requires the sa_session (or custom) cookie to be present on the request.
@@ -8,8 +8,13 @@ import { verifySignedAuthResponse } from "./verifySignedAuthResponse.js";
  * @param authServerUrl Base URL of the client's auth server
  * @returns The user data object if valid, or null if invalid/unauthenticated
  */
-export async function getSeamlessUser(req, authServerUrl) {
+export async function getSeamlessUser(req, authServerUrl, cookieName = "seamless-auth-access") {
     try {
+        const payload = verifyCookieJwt(req.cookies[cookieName]);
+        if (!payload) {
+            throw new Error("Missing cookie");
+        }
+        req.cookiePayload = payload;
         const response = await authFetch(req, `${authServerUrl}/users/me`, {
             method: "GET",
         });
@@ -18,13 +23,6 @@ export async function getSeamlessUser(req, authServerUrl) {
             return null;
         }
         const data = (await response.json());
-        const verified = await verifySignedAuthResponse(data.token, authServerUrl);
-        if (!verified) {
-            throw new Error("Invalid signed response from Auth Server");
-        }
-        if (verified.sub !== data.sub) {
-            throw new Error("Signature mismatch with data payload");
-        }
         return data.user;
     }
     catch (err) {

package/dist/internal/refreshAccessToken.d.ts

@@ -0,0 +1,9 @@
+import { CookieRequest } from "../middleware/ensureCookies.js";
+export declare function refreshAccessToken(req: CookieRequest, authServerUrl: string, refreshToken: string): Promise<{
+    sub: string;
+    token: string;
+    refreshToken: string;
+    roles: string[];
+    ttl: number;
+    refreshTtl: number;
+} | null>;

package/dist/internal/refreshAccessToken.js

@@ -0,0 +1,43 @@
+import jwt from "jsonwebtoken";
+const COOKIE_SECRET = process.env.SEAMLESS_COOKIE_SIGNING_KEY;
+if (!COOKIE_SECRET) {
+    console.warn("[SeamlessAuth] SEAMLESS_COOKIE_SIGNING_KEY missing — requireAuth will always fail.");
+}
+const serviceKey = process.env.SEAMLESS_SERVICE_TOKEN;
+export async function refreshAccessToken(req, authServerUrl, refreshToken) {
+    try {
+        if (!serviceKey) {
+            throw new Error("Cannot sign service token. Missing SEAMLESS_SERVICE_TOKEN");
+        }
+        // unwrap token with local key and rewrap with service key
+        const payload = jwt.verify(refreshToken, COOKIE_SECRET, {
+            algorithms: ["HS256"],
+        });
+        const token = jwt.sign({
+            // Minimal, safe fields
+            iss: process.env.FRONTEND_URL,
+            aud: process.env.AUTH_SERVER,
+            sub: payload.sub,
+            refreshToken: payload.refreshToken,
+            iat: Math.floor(Date.now() / 1000),
+        }, serviceKey, {
+            expiresIn: "60s", // Short-lived = safer
+            algorithm: "HS256", // HMAC-based
+            keyid: "dev-main", // For future rotation
+        });
+        const response = await fetch(`${authServerUrl}/refresh`, {
+            method: "GET",
+            headers: { Authorization: `Bearer ${token}` },
+        });
+        if (!response.ok) {
+            console.error("[SeamlessAuth] Refresh token request failed:", response.status);
+            return null;
+        }
+        const data = await response.json();
+        return data;
+    }
+    catch (err) {
+        console.error("[SeamlessAuth] refreshAccessToken error:", err);
+        return null;
+    }
+}

package/dist/internal/verifySignedAuthResponse.js

@@ -12,6 +12,7 @@ export async function verifySignedAuthResponse(token, authServerUrl) {
         // Verify signature and algorithm
         const { payload } = await jwtVerify(token, JWKS, {
             algorithms: ["RS256"],
+            issuer: authServerUrl,
         });
         return payload;
     }

package/dist/middleware/ensureCookies.d.ts

@@ -4,4 +4,4 @@ import { JwtPayload } from "jsonwebtoken";
 export interface CookieRequest extends Request {
     cookiePayload?: JwtPayload;
 }
-export declare function createEnsureCookiesMiddleware(opts: SeamlessAuthServerOptions): (req: CookieRequest, res: Response, next: NextFunction) => void | Response<any, Record<string, any>>;
+export declare function createEnsureCookiesMiddleware(opts: SeamlessAuthServerOptions): (req: CookieRequest, res: Response, next: NextFunction, cookieDomain?: string) => Promise<void | Response<any, Record<string, any>>>;

package/dist/middleware/ensureCookies.js

@@ -1,32 +1,88 @@
 import { verifyCookieJwt } from "../internal/verifyCookieJwt.js";
+import { refreshAccessToken } from "../internal/refreshAccessToken";
+import { clearAllCookies, setSessionCookie } from "../internal/cookie";
+const AUTH_SERVER_URL = process.env.AUTH_SERVER;
+const COOKIE_SECRET = process.env.SEAMLESS_COOKIE_SIGNING_KEY;
+if (!COOKIE_SECRET) {
+    console.warn("[SeamlessAuth] SEAMLESS_COOKIE_SIGNING_KEY missing — requireAuth will always fail.");
+}
 export function createEnsureCookiesMiddleware(opts) {
     const COOKIE_REQUIREMENTS = {
         "/webAuthn/login/finish": { name: opts.preAuthCookieName, required: true },
         "/webAuthn/login/start": { name: opts.preAuthCookieName, required: true },
-        "/webAuthn/register/start": { name: opts.registrationCookieName, required: true },
-        "/webAuthn/register/finish": { name: opts.registrationCookieName, required: true },
-        "/otp/verify-email-otp": { name: opts.registrationCookieName, required: true },
-        "/otp/verify-phone-otp": { name: opts.registrationCookieName, required: true },
+        "/webAuthn/register/start": {
+            name: opts.registrationCookieName,
+            required: true,
+        },
+        "/webAuthn/register/finish": {
+            name: opts.registrationCookieName,
+            required: true,
+        },
+        "/otp/verify-email-otp": {
+            name: opts.registrationCookieName,
+            required: true,
+        },
+        "/otp/verify-phone-otp": {
+            name: opts.registrationCookieName,
+            required: true,
+        },
         "/logout": { name: opts.accesscookieName, required: true },
         "/users/me": { name: opts.accesscookieName, required: true },
     };
-    return function ensureCookies(req, res, next) {
+    return async function ensureCookies(req, res, next, cookieDomain = "") {
         const match = Object.entries(COOKIE_REQUIREMENTS).find(([path]) => req.path.startsWith(path));
         if (!match)
             return next();
         const [, { name, required }] = match;
         const cookieValue = req.cookies?.[name];
+        const refreshCookieValue = req.cookies?.[opts.refreshCookieName];
+        //
+        // --- NEW REFRESH-AWARE LOGIC ---
+        //
+        // If required cookie is missing BUT refresh cookie exists,
+        // allow request to proceed. requireAuth() will perform refresh.
+        //
         if (required && !cookieValue) {
+            if (refreshCookieValue) {
+                console.log("[SeamlessAuth] Access token expired — attempting refresh");
+                const refreshed = await refreshAccessToken(req, AUTH_SERVER_URL, refreshCookieValue);
+                if (!refreshed?.token) {
+                    clearAllCookies(res, cookieDomain, name, opts.registrationCookieName, opts.refreshCookieName);
+                    res.status(401).json({ error: "Refresh failed" });
+                    return;
+                }
+                // Update cookie with new access token
+                setSessionCookie(res, {
+                    sub: refreshed.sub,
+                    token: refreshed.token,
+                    roles: refreshed.roles,
+                }, cookieDomain, refreshed.ttl, name);
+                setSessionCookie(res, { sub: refreshed.sub, refreshToken: refreshed.refreshToken }, cookieDomain, refreshed.refreshTtl, opts.refreshCookieName);
+                // Let requireAuth() attempt refresh
+                req.cookiePayload = {
+                    sub: refreshed.sub,
+                    roles: refreshed.roles,
+                };
+                return next();
+            }
+            // No required cookie AND no refresh cookie → hard fail
             return res.status(400).json({
                 error: `Missing required cookie "${name}" for route ${req.path}`,
                 hint: "Did you forget to call /auth/login/start first?",
             });
         }
-        const payload = verifyCookieJwt(cookieValue);
-        if (!payload) {
-            return res.status(401).json({ error: `Invalid or expired ${name} cookie` });
+        //
+        // If cookie exists, verify it normally
+        //
+        if (cookieValue) {
+            const payload = verifyCookieJwt(cookieValue);
+            if (!payload) {
+                return res
+                    .status(401)
+                    .json({ error: `Invalid or expired ${name} cookie` });
+            }
+            req.cookiePayload = payload;
         }
-        req.cookiePayload = payload;
         next();
     };
 }

package/dist/middleware/requireAuth.d.ts

@@ -5,4 +5,4 @@ import { Request, Response, NextFunction } from "express";
  * - Attaches decoded payload to req.user
  * - Returns 401 if missing/invalid/expired
  */
-export declare function requireAuth(cookieName?: string): (req: Request, res: Response, next: NextFunction) => void;
+export declare function requireAuth(cookieName?: string, refreshCookieName?: string, cookieDomain?: string): (req: Request, res: Response, next: NextFunction) => Promise<void>;

package/dist/middleware/requireAuth.js

@@ -1,28 +1,65 @@
 import jwt from "jsonwebtoken";
+import { refreshAccessToken } from "../internal/refreshAccessToken.js";
+import { setSessionCookie } from "../internal/cookie.js";
 const COOKIE_SECRET = process.env.SEAMLESS_COOKIE_SIGNING_KEY;
 if (!COOKIE_SECRET) {
     console.warn("[SeamlessAuth] SEAMLESS_COOKIE_SIGNING_KEY missing — requireAuth will always fail.");
 }
+const AUTH_SERVER_URL = process.env.AUTH_SERVER;
 /**
  * Express middleware that verifies a Seamless Auth access cookie.
  * - Reads and verifies signed cookie JWT
  * - Attaches decoded payload to req.user
  * - Returns 401 if missing/invalid/expired
  */
-export function requireAuth(cookieName = "seamless-auth-access") {
-    return (req, res, next) => {
+export function requireAuth(cookieName = "seamless-auth-access", refreshCookieName = "seamless-auth-refresh", cookieDomain = "/") {
+    return async (req, res, next) => {
         try {
             const token = req.cookies?.[cookieName];
             if (!token) {
                 res.status(401).json({ error: "Missing access cookie" });
                 return;
             }
-            const payload = jwt.verify(token, COOKIE_SECRET, {
-                algorithms: ["HS256"],
-            });
-            // Attach decoded JWT claims to request for downstream handlers
-            req.user = payload;
-            next();
+            try {
+                const payload = jwt.verify(token, COOKIE_SECRET, {
+                    algorithms: ["HS256"],
+                });
+                req.user = payload;
+                return next();
+            }
+            catch (err) {
+                // expired or invalid token
+                if (err.name !== "TokenExpiredError") {
+                    console.warn("[SeamlessAuth] Invalid token:", err.message);
+                    res.status(401).json({ error: "Invalid token" });
+                    return;
+                }
+                // Try refresh
+                const refreshToken = req.cookies?.[refreshCookieName];
+                if (!refreshToken) {
+                    res.status(401).json({ error: "Session expired; re-login required" });
+                    return;
+                }
+                console.log("[SeamlessAuth] Access token expired — attempting refresh");
+                const refreshed = await refreshAccessToken(req, AUTH_SERVER_URL, refreshToken);
+                if (!refreshed?.token) {
+                    res.status(401).json({ error: "Refresh failed" });
+                    return;
+                }
+                // Update cookie with new access token
+                setSessionCookie(res, {
+                    sub: refreshed.sub,
+                    token: refreshed.token,
+                    roles: refreshed.roles,
+                }, cookieDomain, refreshed.ttl, cookieName);
+                setSessionCookie(res, { sub: refreshed.sub, refreshToken: refreshed.refreshToken }, req.hostname, refreshed.refreshTtl, refreshCookieName);
+                // Decode new token so downstream has user
+                const payload = jwt.verify(refreshed.token, COOKIE_SECRET, {
+                    algorithms: ["HS256"],
+                });
+                req.user = payload;
+                next();
+            }
         }
         catch (err) {
             console.error("[SeamlessAuth] requireAuth error:", err.message);

package/dist/middleware/requireRole.js

@@ -9,7 +9,7 @@ if (!COOKIE_SECRET) {
  * @param role        Role name to require (e.g. 'admin')
  * @param cookieName  Cookie name containing JWT (default: 'sa_session')
  */
-export function requireRole(role, cookieName = "seamless-auth-access") {
+export function requireRole(role, cookieName = "seamless-access") {
     return (req, res, next) => {
         try {
             const token = req.cookies?.[cookieName];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamless-auth/express",
-  "version": "0.0.0",
+  "version": "0.0.1-beta.3",
   "description": "Express adapter for Seamless Auth passwordless authentication",
   "license": "MIT",
   "type": "module",
@@ -13,7 +13,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/fells-code/seamless-auth-server"
+    "url": "git+https://github.com/fells-code/seamless-auth-server.git"
   },
   "files": [
     "dist"
@@ -26,12 +26,9 @@
     "cookie-parser": "^1.4.6",
     "jose": "^6.1.1",
     "jsonwebtoken": "^9.0.2",
-    "node-fetch": "^3.3.2",
-    "version-packages": "changeset version",
-    "release": "changeset publish"
+    "node-fetch": "^3.3.2"
   },
   "devDependencies": {
-    "@changesets/cli": "^2.29.7",
     "@types/cookie-parser": "^1.4.10",
     "@types/jsonwebtoken": "^9.0.10",
     "typescript": "^5.5.0"