@seamless-auth/express 0.0.1 → 0.0.2-beta.1

package/README.md

@@ -96,13 +96,12 @@ Everything happens securely between your API and a 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`             |
+| 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        | `Obtained via the auth portal` |
+| `FRONTEND_URL`                | URL of your website or https://localhost:5001 | `https://mySite.com`           |
 
 ---
 
@@ -188,7 +187,7 @@ User shape
    → sets short-lived pre-auth cookie.
 
 2. **Frontend** → `/auth/webauthn/finish`  
-   → API proxies, validates, sets access cookie (`seamless_auth_access`).
+   → API proxies, validates, sets access cookie (`seamless-access`).
 
 3. **Subsequent API calls** → `/api/...`  
    → `requireAuth()` verifies cookie and attaches user.  
@@ -206,9 +205,10 @@ In order to develop with your Seamless Auth server instance, you will need to ha
 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
+AUTH_SERVER_URL=https://<identifier>.seamlessauth.com # Found in the portal
+SEAMLESS_SERVICE_TOKEN=32byte-secret # Created and rotated in the portal
+FRONTEND_URL=https://yourSite.com # Must match the value you have for Frontend Domain in the portal (Can be localhost:5001 when application is in demo mode)
+SEAMLESS_COOKIE_SIGNING_KEY=local-secret-key # A key you make for signing your API's distributed cookies
 ```
 
 ---
@@ -217,7 +217,7 @@ SEAMLESS_COOKIE_SIGNING_KEY=local-secret-key # Found in the portal
 
 ```ts
 const AUTH_SERVER_URL = process.env.AUTH_SERVER_URL!;
-app.use(cors({ origin: "http://localhost:5001", credentials: true }));
+app.use(cors({ origin: "https://localhost:5001", credentials: true }));
 app.use(express.json());
 app.use(cookieParser());
 app.use("/auth", createSeamlessAuthServer({ authServerUrl: AUTH_SERVER_URL }));
@@ -266,3 +266,4 @@ app.get("/api/test", requireAuth(), (req, res) => res.json({ ok: true }));
 
 MIT © 2025 Fells Code LLC  
 Part of the **Seamless Auth** ecosystem.
+https://seamlessauth.com

package/dist/createServer.d.ts

@@ -1,4 +1,48 @@
 import { Router } from "express";
 import type { SeamlessAuthServerOptions } from "./types";
+/**
+ * Creates an Express Router that proxies all authentication traffic to a Seamless Auth server.
+ *
+ * This helper wires your API backend to a Seamless Auth instance running in
+ * "server mode." It automatically forwards login, registration, WebAuthn,
+ * logout, token refresh, and session validation routes to the auth server
+ * and handles all cookie management required for a seamless login flow.
+ *
+ * ### Responsibilities
+ * - Proxies all `/auth/*` routes to the upstream Seamless Auth server
+ * - Manages `access`, `registration`, `pre-auth`, and `refresh` cookies
+ * - Normalizes cookie settings for cross-domain or same-domain deployments
+ * - Ensures authentication routes behave consistently across environments
+ * - Provides shared middleware for auth flows
+ *
+ * ### Cookie Types
+ * - **accessCookie** – long-lived session cookie for authenticated API requests
+ * - **registrationCookie** – ephemeral cookie used during registration and OTP/WebAuthn flows
+ * - **preAuthCookie** – short-lived cookie used during login initiation
+ * - **refreshCookie** – opaque refresh token cookie used to rotate session tokens
+ *
+ * All cookie names and their domains may be customized via the `opts` parameter.
+ *
+ * ### Example
+ * ```ts
+ * app.use("/auth", createSeamlessAuthServer({
+ *   authServerUrl: "https://identifier.seamlessauth.com",
+ *   cookieDomain: "mycompany.com",
+ *   accesscookieName: "sa_access",
+ *   registrationCookieName: "sa_registration",
+ *   refreshCookieName: "sa_refresh",
+ * }));
+ * ```
+ *
+ * @param opts - Configuration options for the Seamless Auth proxy:
+ *   - `authServerUrl` — Base URL of your Seamless Auth instance (required)
+ *   - `cookieDomain` — Domain attribute applied to all auth cookies
+ *   - `accesscookieName` — Name of the session access cookie
+ *   - `registrationCookieName` — Name of the ephemeral registration cookie
+ *   - `refreshCookieName` — Name of the refresh token cookie
+ *   - `preAuthCookieName` — Name of the cookie used during login initiation
+ *
+ * @returns An Express `Router` preconfigured with all Seamless Auth routes.
+ */
 export declare function createSeamlessAuthServer(opts: SeamlessAuthServerOptions): Router;
 //# sourceMappingURL=createServer.d.ts.map

package/dist/createServer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"createServer.d.ts","sourceRoot":"","sources":["../src/createServer.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAqB,MAAM,EAAE,MAAM,SAAS,CAAC;AAQ7D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AAIzD,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,yBAAyB,GAC9B,MAAM,CA6LR"}
+{"version":3,"file":"createServer.d.ts","sourceRoot":"","sources":["../src/createServer.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAqB,MAAM,EAAE,MAAM,SAAS,CAAC;AAQ7D,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AAIzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,yBAAyB,GAC9B,MAAM,CA0LR"}

package/dist/createServer.js

@@ -1,9 +1,53 @@
 import express from "express";
 import cookieParser from "cookie-parser";
-import { setSessionCookie, clearAllCookies, clearSessionCookie, } from "./internal/cookie";
-import { authFetch } from "./internal/authFetch";
-import { createEnsureCookiesMiddleware } from "./middleware/ensureCookies";
-import { verifySignedAuthResponse } from "./internal/verifySignedAuthResponse";
+import { setSessionCookie, clearAllCookies, clearSessionCookie, } from './internal/cookie.js';
+import { authFetch } from './internal/authFetch.js';
+import { createEnsureCookiesMiddleware } from './middleware/ensureCookies.js';
+import { verifySignedAuthResponse } from './internal/verifySignedAuthResponse.js';
+/**
+ * Creates an Express Router that proxies all authentication traffic to a Seamless Auth server.
+ *
+ * This helper wires your API backend to a Seamless Auth instance running in
+ * "server mode." It automatically forwards login, registration, WebAuthn,
+ * logout, token refresh, and session validation routes to the auth server
+ * and handles all cookie management required for a seamless login flow.
+ *
+ * ### Responsibilities
+ * - Proxies all `/auth/*` routes to the upstream Seamless Auth server
+ * - Manages `access`, `registration`, `pre-auth`, and `refresh` cookies
+ * - Normalizes cookie settings for cross-domain or same-domain deployments
+ * - Ensures authentication routes behave consistently across environments
+ * - Provides shared middleware for auth flows
+ *
+ * ### Cookie Types
+ * - **accessCookie** – long-lived session cookie for authenticated API requests
+ * - **registrationCookie** – ephemeral cookie used during registration and OTP/WebAuthn flows
+ * - **preAuthCookie** – short-lived cookie used during login initiation
+ * - **refreshCookie** – opaque refresh token cookie used to rotate session tokens
+ *
+ * All cookie names and their domains may be customized via the `opts` parameter.
+ *
+ * ### Example
+ * ```ts
+ * app.use("/auth", createSeamlessAuthServer({
+ *   authServerUrl: "https://identifier.seamlessauth.com",
+ *   cookieDomain: "mycompany.com",
+ *   accesscookieName: "sa_access",
+ *   registrationCookieName: "sa_registration",
+ *   refreshCookieName: "sa_refresh",
+ * }));
+ * ```
+ *
+ * @param opts - Configuration options for the Seamless Auth proxy:
+ *   - `authServerUrl` — Base URL of your Seamless Auth instance (required)
+ *   - `cookieDomain` — Domain attribute applied to all auth cookies
+ *   - `accesscookieName` — Name of the session access cookie
+ *   - `registrationCookieName` — Name of the ephemeral registration cookie
+ *   - `refreshCookieName` — Name of the refresh token cookie
+ *   - `preAuthCookieName` — Name of the cookie used during login initiation
+ *
+ * @returns An Express `Router` preconfigured with all Seamless Auth routes.
+ */
 export function createSeamlessAuthServer(opts) {
     const r = express.Router();
     r.use(express.json());

package/dist/index.js

@@ -1,5 +1,5 @@
-import { createSeamlessAuthServer } from "./createServer";
-export { requireAuth } from "./middleware/requireAuth";
-export { requireRole } from "./middleware/requireRole";
-export { getSeamlessUser } from "./internal/getSeamlessUser";
+import { createSeamlessAuthServer } from './createServer.js';
+export { requireAuth } from './middleware/requireAuth.js';
+export { requireRole } from './middleware/requireRole.js';
+export { getSeamlessUser } from './internal/getSeamlessUser.js';
 export default createSeamlessAuthServer;

package/dist/internal/authFetch.d.ts

@@ -1,6 +1,6 @@
 import { CookieRequest } from "../middleware/ensureCookies";
 export interface AuthFetchOptions {
-    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    method?: "GET" | "POST" | "PUT" | "DELETE";
     body?: any;
     cookies?: string[];
     headers?: Record<string, string>;

package/dist/internal/authFetch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"authFetch.d.ts","sourceRoot":"","sources":["../../src/internal/authFetch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACrD,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,wBAAsB,SAAS,CAC7B,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,EACX,EAAE,MAAe,EAAE,IAAI,EAAE,OAAO,EAAE,OAAY,EAAE,GAAE,gBAAqB,qBAuDxE"}
+{"version":3,"file":"authFetch.d.ts","sourceRoot":"","sources":["../../src/internal/authFetch.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,QAAQ,CAAC;IAC3C,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,wBAAsB,SAAS,CAC7B,GAAG,EAAE,aAAa,EAClB,GAAG,EAAE,MAAM,EACX,EAAE,MAAe,EAAE,IAAI,EAAE,OAAO,EAAE,OAAY,EAAE,GAAE,gBAAqB,qBAiDxE"}

package/dist/internal/authFetch.js

@@ -4,30 +4,26 @@ export async function authFetch(req, url, { method = "POST", body, cookies, head
     if (!serviceKey) {
         throw new Error("Cannot sign service token. Missing SEAMLESS_SERVICE_TOKEN");
     }
-    console.debug("[SeamlessAuth] Performing authentication fetch to Auth server");
     // -------------------------------
     // Issue short-lived machine token
     // -------------------------------
     const token = jwt.sign({
-        // Minimal, safe fields
         iss: process.env.FRONTEND_URL,
         aud: process.env.AUTH_SERVER_URL,
         sub: req.cookiePayload?.sub,
         roles: req.cookiePayload?.roles ?? [],
         iat: Math.floor(Date.now() / 1000),
     }, serviceKey, {
-        expiresIn: "60s", // Short-lived = safer
+        expiresIn: "60s", // Short-lived
         algorithm: "HS256", // HMAC-based
-        keyid: "dev-main", // For future rotation
     });
     const finalHeaders = {
         ...(method !== "GET" && { "Content-Type": "application/json" }),
         ...(cookies ? { Cookie: cookies.join("; ") } : {}),
-        Authorization: `Bearer ${serviceKey}`,
+        Authorization: `Bearer ${token}`,
         ...headers,
     };
     let finalUrl = url;
-    console.debug("[SeamlessAuth] URL ...", finalUrl);
     if (method === "GET" && body && typeof body === "object") {
         const qs = new URLSearchParams(body).toString();
         finalUrl += url.includes("?") ? `&${qs}` : `?${qs}`;

package/dist/internal/getSeamlessUser.d.ts

@@ -1,11 +1,51 @@
 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.
+ * Retrieves the authenticated Seamless Auth user for a request by calling
+ * the upstream Seamless Auth Server’s introspection endpoint.
  *
- * @param req Express request object
- * @param authServerUrl Base URL of the client's auth server
- * @returns The user data object if valid, or null if invalid/unauthenticated
+ * This helper is used when server-side code needs the fully hydrated
+ * Seamless Auth user object (including roles, metadata, and profile fields),
+ * not just the JWT payload extracted from cookies.
+ *
+ * Unlike `requireAuth`, this helper does **not** enforce authentication.
+ * It simply returns:
+ * - The resolved user object (if the session is valid)
+ * - `null` if the session is invalid, expired, or missing
+ *
+ * ### Responsibilities
+ * - Extracts the access cookie (or refresh cookie when needed)
+ * - Calls the Seamless Auth Server’s `/internal/session/introspect` endpoint
+ * - Validates whether the session is active
+ * - Returns the user object or `null` without throwing
+ *
+ * ### Use Cases
+ * - Fetching the current user in internal APIs
+ * - Enriching backend requests with server-authoritative user information
+ * - Logging, analytics, auditing
+ * - Optional-auth routes that behave differently for signed-in users
+ *
+ * ### Example
+ * ```ts
+ * app.get("/portal/me", async (req, res) => {
+ *   const user = await getSeamlessUser(req, process.env.SA_AUTH_SERVER_URL);
+ *
+ *   if (!user) {
+ *     return res.json({ user: null });
+ *   }
+ *
+ *   return res.json({ user });
+ * });
+ * ```
+ *
+ * ### Returns
+ * - A full Seamless Auth user object (if active)
+ * - `null` if not authenticated or session expired
+ *
+ * @param req - The Express request object containing auth cookies.
+ * @param authServerUrl - Base URL of the Seamless Auth instance to introspect against.
+ * @param cookieName - Name of the access cookie storing the session JWT (`"seamless-access"` by default).
+ *
+ * @returns The authenticated user object, or `null` if the session is inactive.
  */
 export declare function getSeamlessUser<T = any>(req: CookieRequest, authServerUrl: string, cookieName?: string): Promise<T | null>;
 //# sourceMappingURL=getSeamlessUser.d.ts.map

package/dist/internal/getSeamlessUser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getSeamlessUser.d.ts","sourceRoot":"","sources":["../../src/internal/getSeamlessUser.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAG/D;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,CAAC,GAAG,GAAG,EAC3C,GAAG,EAAE,aAAa,EAClB,aAAa,EAAE,MAAM,EACrB,UAAU,GAAE,MAA+B,GAC1C,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAwBnB"}
+{"version":3,"file":"getSeamlessUser.d.ts","sourceRoot":"","sources":["../../src/internal/getSeamlessUser.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAG/D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,wBAAsB,eAAe,CAAC,CAAC,GAAG,GAAG,EAC3C,GAAG,EAAE,aAAa,EAClB,aAAa,EAAE,MAAM,EACrB,UAAU,GAAE,MAA0B,GACrC,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAwBnB"}

package/dist/internal/getSeamlessUser.js

@@ -1,14 +1,54 @@
 import { authFetch } from "./authFetch.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.
+ * Retrieves the authenticated Seamless Auth user for a request by calling
+ * the upstream Seamless Auth Server’s introspection endpoint.
  *
- * @param req Express request object
- * @param authServerUrl Base URL of the client's auth server
- * @returns The user data object if valid, or null if invalid/unauthenticated
+ * This helper is used when server-side code needs the fully hydrated
+ * Seamless Auth user object (including roles, metadata, and profile fields),
+ * not just the JWT payload extracted from cookies.
+ *
+ * Unlike `requireAuth`, this helper does **not** enforce authentication.
+ * It simply returns:
+ * - The resolved user object (if the session is valid)
+ * - `null` if the session is invalid, expired, or missing
+ *
+ * ### Responsibilities
+ * - Extracts the access cookie (or refresh cookie when needed)
+ * - Calls the Seamless Auth Server’s `/internal/session/introspect` endpoint
+ * - Validates whether the session is active
+ * - Returns the user object or `null` without throwing
+ *
+ * ### Use Cases
+ * - Fetching the current user in internal APIs
+ * - Enriching backend requests with server-authoritative user information
+ * - Logging, analytics, auditing
+ * - Optional-auth routes that behave differently for signed-in users
+ *
+ * ### Example
+ * ```ts
+ * app.get("/portal/me", async (req, res) => {
+ *   const user = await getSeamlessUser(req, process.env.SA_AUTH_SERVER_URL);
+ *
+ *   if (!user) {
+ *     return res.json({ user: null });
+ *   }
+ *
+ *   return res.json({ user });
+ * });
+ * ```
+ *
+ * ### Returns
+ * - A full Seamless Auth user object (if active)
+ * - `null` if not authenticated or session expired
+ *
+ * @param req - The Express request object containing auth cookies.
+ * @param authServerUrl - Base URL of the Seamless Auth instance to introspect against.
+ * @param cookieName - Name of the access cookie storing the session JWT (`"seamless-access"` by default).
+ *
+ * @returns The authenticated user object, or `null` if the session is inactive.
  */
-export async function getSeamlessUser(req, authServerUrl, cookieName = "seamless-auth-access") {
+export async function getSeamlessUser(req, authServerUrl, cookieName = "seamless-access") {
     try {
         const payload = verifyCookieJwt(req.cookies[cookieName]);
         if (!payload) {

package/dist/middleware/ensureCookies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ensureCookies.d.ts","sourceRoot":"","sources":["../../src/middleware/ensureCookies.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAGrD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI1C,MAAM,WAAW,aAAc,SAAQ,OAAO;IAC5C,aAAa,CAAC,EAAE,UAAU,CAAC;CAC5B;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,yBAAyB,IA4BzE,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,MAAM,YAAY,EAClB,qBAAiB,wDA2FpB"}
+{"version":3,"file":"ensureCookies.d.ts","sourceRoot":"","sources":["../../src/middleware/ensureCookies.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC1D,OAAO,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;AAGrD,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAI1C,MAAM,WAAW,aAAc,SAAQ,OAAO;IAC5C,aAAa,CAAC,EAAE,UAAU,CAAC;CAC5B;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,yBAAyB,IA4BzE,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,MAAM,YAAY,EAClB,qBAAiB,wDAqFpB"}

package/dist/middleware/ensureCookies.js

@@ -32,12 +32,6 @@ export function createEnsureCookiesMiddleware(opts) {
         const AUTH_SERVER_URL = process.env.AUTH_SERVER;
         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");
@@ -61,7 +55,7 @@ export function createEnsureCookiesMiddleware(opts) {
                 };
                 return next();
             }
-            // No required cookie AND no refresh cookie → hard fail
+            // No required cookie AND no refresh cookie
             return res.status(400).json({
                 error: `Missing required cookie "${name}" for route ${req.path}`,
                 hint: "Did you forget to call /auth/login/start first?",

package/dist/middleware/requireAuth.d.ts

@@ -1,9 +1,53 @@
 import { Request, Response, NextFunction } from "express";
 /**
- * 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
+ * Express middleware that enforces authentication using Seamless Auth cookies.
+ *
+ * This guard verifies the signed access cookie generated by the Seamless Auth
+ * server. If the access cookie is valid and unexpired, the decoded session
+ * payload is attached to `req.user` and the request proceeds.
+ *
+ * If the access cookie is expired or missing *but* a valid refresh cookie is
+ * present, the middleware automatically attempts a silent token refresh using
+ * the Seamless Auth server. When successful, new session cookies are issued and
+ * the request continues with an updated `req.user`.
+ *
+ * If neither the access token nor refresh token can validate the session,
+ * the middleware returns a 401 Unauthorized error and prevents further
+ * route execution.
+ *
+ * ### Responsibilities
+ * - Validates the Seamless Auth session access cookie
+ * - Attempts refresh-token–based session renewal when necessary
+ * - Populates `req.user` with the verified session payload
+ * - Handles all cookie rewriting during refresh flows
+ * - Acts as a request-level authentication guard for API routes
+ *
+ * ### Cookie Parameters
+ * - **cookieName** — Name of the access cookie that holds the signed session JWT
+ * - **refreshCookieName** — Name of the refresh cookie used for silent token refresh
+ * - **cookieDomain** — Domain or path value applied to issued cookies
+ *
+ * ### Example
+ * ```ts
+ * // Protect a route
+ * app.get("/api/me", requireAuth(), (req, res) => {
+ *   res.json({ user: req.user });
+ * });
+ *
+ * // Custom cookie names (if your Seamless Auth server uses overrides)
+ * app.use(
+ *   "/internal",
+ *   requireAuth("sa_access", "sa_refresh", "mycompany.com"),
+ *   internalRouter
+ * );
+ * ```
+ *
+ * @param cookieName - The access cookie name. Defaults to `"seamless-access"`.
+ * @param refreshCookieName - The refresh cookie name used for session rotation. Defaults to `"seamless-refresh"`.
+ * @param cookieDomain - Domain or path used when rewriting cookies. Defaults to `"/"`.
+ *
+ * @returns An Express middleware function that enforces Seamless Auth
+ *          authentication on incoming requests.
  */
 export declare function requireAuth(cookieName?: string, refreshCookieName?: string, cookieDomain?: string): (req: Request, res: Response, next: NextFunction) => Promise<void>;
 //# sourceMappingURL=requireAuth.d.ts.map

package/dist/middleware/requireAuth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"requireAuth.d.ts","sourceRoot":"","sources":["../../src/middleware/requireAuth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAM1D;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,UAAU,SAAyB,EACnC,iBAAiB,SAA0B,EAC3C,YAAY,SAAM,IAahB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,MAAM,YAAY,KACjB,OAAO,CAAC,IAAI,CAAC,CA+EjB"}
+{"version":3,"file":"requireAuth.d.ts","sourceRoot":"","sources":["../../src/middleware/requireAuth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAM1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,WAAW,CACzB,UAAU,SAAoB,EAC9B,iBAAiB,SAAqB,EACtC,YAAY,SAAM,IAahB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,MAAM,YAAY,KACjB,OAAO,CAAC,IAAI,CAAC,CA+EjB"}

package/dist/middleware/requireAuth.js

@@ -2,18 +2,62 @@ import jwt from "jsonwebtoken";
 import { refreshAccessToken } from "../internal/refreshAccessToken.js";
 import { setSessionCookie } from "../internal/cookie.js";
 /**
- * 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
+ * Express middleware that enforces authentication using Seamless Auth cookies.
+ *
+ * This guard verifies the signed access cookie generated by the Seamless Auth
+ * server. If the access cookie is valid and unexpired, the decoded session
+ * payload is attached to `req.user` and the request proceeds.
+ *
+ * If the access cookie is expired or missing *but* a valid refresh cookie is
+ * present, the middleware automatically attempts a silent token refresh using
+ * the Seamless Auth server. When successful, new session cookies are issued and
+ * the request continues with an updated `req.user`.
+ *
+ * If neither the access token nor refresh token can validate the session,
+ * the middleware returns a 401 Unauthorized error and prevents further
+ * route execution.
+ *
+ * ### Responsibilities
+ * - Validates the Seamless Auth session access cookie
+ * - Attempts refresh-token–based session renewal when necessary
+ * - Populates `req.user` with the verified session payload
+ * - Handles all cookie rewriting during refresh flows
+ * - Acts as a request-level authentication guard for API routes
+ *
+ * ### Cookie Parameters
+ * - **cookieName** — Name of the access cookie that holds the signed session JWT
+ * - **refreshCookieName** — Name of the refresh cookie used for silent token refresh
+ * - **cookieDomain** — Domain or path value applied to issued cookies
+ *
+ * ### Example
+ * ```ts
+ * // Protect a route
+ * app.get("/api/me", requireAuth(), (req, res) => {
+ *   res.json({ user: req.user });
+ * });
+ *
+ * // Custom cookie names (if your Seamless Auth server uses overrides)
+ * app.use(
+ *   "/internal",
+ *   requireAuth("sa_access", "sa_refresh", "mycompany.com"),
+ *   internalRouter
+ * );
+ * ```
+ *
+ * @param cookieName - The access cookie name. Defaults to `"seamless-access"`.
+ * @param refreshCookieName - The refresh cookie name used for session rotation. Defaults to `"seamless-refresh"`.
+ * @param cookieDomain - Domain or path used when rewriting cookies. Defaults to `"/"`.
+ *
+ * @returns An Express middleware function that enforces Seamless Auth
+ *          authentication on incoming requests.
  */
-export function requireAuth(cookieName = "seamless-auth-access", refreshCookieName = "seamless-auth-refresh", cookieDomain = "/") {
+export function requireAuth(cookieName = "seamless-access", refreshCookieName = "seamless-refresh", cookieDomain = "/") {
     const COOKIE_SECRET = process.env.SEAMLESS_COOKIE_SIGNING_KEY;
     if (!COOKIE_SECRET) {
         console.warn("[SeamlessAuth] SEAMLESS_COOKIE_SIGNING_KEY missing — requireAuth will always fail.");
         throw new Error("Missing required env SEAMLESS_COOKIE_SIGNING_KEY");
     }
-    const AUTH_SERVER_URL = process.env.AUTH_SERVER;
+    const AUTH_SERVER_URL = process.env.AUTH_SERVER_URL;
     return async (req, res, next) => {
         try {
             if (!COOKIE_SECRET) {

package/dist/middleware/requireRole.d.ts

@@ -1,9 +1,49 @@
 import { RequestHandler } from "express";
 /**
- * Express middleware to enforce a required role from Seamless Auth cookie JWT.
+ * Express middleware that enforces role-based authorization for Seamless Auth sessions.
  *
- * @param role        Role name to require (e.g. 'admin')
- * @param cookieName  Cookie name containing JWT (default: 'sa_session')
+ * This guard assumes that `requireAuth()` has already validated the request
+ * and populated `req.user` with the decoded Seamless Auth session payload.
+ * It then checks whether the user’s roles include the required role (or any
+ * of several, when an array is provided).
+ *
+ * If the user possesses the required authorization, the request proceeds.
+ * Otherwise, the middleware responds with a 403 Forbidden error.
+ *
+ * ### Responsibilities
+ * - Validates that `req.user` is present (enforced upstream by `requireAuth`)
+ * - Ensures the authenticated user includes the specified role(s)
+ * - Blocks unauthorized access with a standardized JSON 403 response
+ *
+ * ### Parameters
+ * - **requiredRole** — A role (string) or list of roles the user must have.
+ *   If an array is provided, *any* matching role grants access.
+ * - **cookieName** — Optional name of the access cookie to inspect.
+ *   Defaults to `"seamless-access"`, but typically not needed because
+ *   `requireAuth` is expected to run first.
+ *
+ * ### Example
+ * ```ts
+ * // Require a single role
+ * app.get("/admin/users",
+ *   requireAuth(),
+ *   requireRole("admin"),
+ *   (req, res) => {
+ *     res.send("Welcome admin!");
+ *   }
+ * );
+ *
+ * // Allow any of multiple roles
+ * app.post("/settings",
+ *   requireAuth(),
+ *   requireRole(["admin", "supervisor"]),
+ *   updateSettingsHandler
+ * );
+ * ```
+ *
+ * @param requiredRole - A role or list of roles required to access the route.
+ * @param cookieName - Optional access cookie name (defaults to `seamless-access`).
+ * @returns An Express middleware function enforcing role-based access control.
  */
 export declare function requireRole(role: string, cookieName?: string): RequestHandler;
 //# sourceMappingURL=requireRole.d.ts.map

package/dist/middleware/requireRole.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"requireRole.d.ts","sourceRoot":"","sources":["../../src/middleware/requireRole.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAC;AAG1E;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,UAAU,SAAoB,GAC7B,cAAc,CAiChB"}
+{"version":3,"file":"requireRole.d.ts","sourceRoot":"","sources":["../../src/middleware/requireRole.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAC;AAG1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,UAAU,SAAoB,GAC7B,cAAc,CAiChB"}

package/dist/middleware/requireRole.js

@@ -1,9 +1,49 @@
 import jwt from "jsonwebtoken";
 /**
- * Express middleware to enforce a required role from Seamless Auth cookie JWT.
+ * Express middleware that enforces role-based authorization for Seamless Auth sessions.
  *
- * @param role        Role name to require (e.g. 'admin')
- * @param cookieName  Cookie name containing JWT (default: 'sa_session')
+ * This guard assumes that `requireAuth()` has already validated the request
+ * and populated `req.user` with the decoded Seamless Auth session payload.
+ * It then checks whether the user’s roles include the required role (or any
+ * of several, when an array is provided).
+ *
+ * If the user possesses the required authorization, the request proceeds.
+ * Otherwise, the middleware responds with a 403 Forbidden error.
+ *
+ * ### Responsibilities
+ * - Validates that `req.user` is present (enforced upstream by `requireAuth`)
+ * - Ensures the authenticated user includes the specified role(s)
+ * - Blocks unauthorized access with a standardized JSON 403 response
+ *
+ * ### Parameters
+ * - **requiredRole** — A role (string) or list of roles the user must have.
+ *   If an array is provided, *any* matching role grants access.
+ * - **cookieName** — Optional name of the access cookie to inspect.
+ *   Defaults to `"seamless-access"`, but typically not needed because
+ *   `requireAuth` is expected to run first.
+ *
+ * ### Example
+ * ```ts
+ * // Require a single role
+ * app.get("/admin/users",
+ *   requireAuth(),
+ *   requireRole("admin"),
+ *   (req, res) => {
+ *     res.send("Welcome admin!");
+ *   }
+ * );
+ *
+ * // Allow any of multiple roles
+ * app.post("/settings",
+ *   requireAuth(),
+ *   requireRole(["admin", "supervisor"]),
+ *   updateSettingsHandler
+ * );
+ * ```
+ *
+ * @param requiredRole - A role or list of roles required to access the route.
+ * @param cookieName - Optional access cookie name (defaults to `seamless-access`).
+ * @returns An Express middleware function enforcing role-based access control.
  */
 export function requireRole(role, cookieName = "seamless-access") {
     return (req, res, next) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamless-auth/express",
-  "version": "0.0.1",
+  "version": "0.0.2-beta.1",
   "description": "Express adapter for Seamless Auth passwordless authentication",
   "license": "MIT",
   "type": "module",