@seamless-auth/express 0.0.1-beta.3 → 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
 ```
 
 ---
@@ -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,3 +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

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,yBAAyB,GAC9B,MAAM,CA0LR"}

package/dist/createServer.js

@@ -4,6 +4,50 @@ import { setSessionCookie, clearAllCookies, clearSessionCookie, } from './intern
 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.d.ts

@@ -4,3 +4,4 @@ export { requireRole } from "./middleware/requireRole";
 export { getSeamlessUser } from "./internal/getSeamlessUser";
 export type { SeamlessAuthServerOptions } from "./types";
 export default createSeamlessAuthServer;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,wBAAwB,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAC5D,YAAY,EAAE,yBAAyB,EAAE,MAAM,SAAS,CAAC;AAEzD,eAAe,wBAAwB,CAAC"}

package/dist/internal/authFetch.d.ts

@@ -1,8 +1,9 @@
 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>;
 }
 export declare function authFetch(req: CookieRequest, url: string, { method, body, cookies, headers }?: AuthFetchOptions): Promise<Response>;
+//# sourceMappingURL=authFetch.d.ts.map

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

@@ -0,0 +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,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

@@ -1,6 +1,6 @@
 import jwt from "jsonwebtoken";
-const serviceKey = process.env.SEAMLESS_SERVICE_TOKEN;
 export async function authFetch(req, url, { method = "POST", body, cookies, headers = {} } = {}) {
+    const serviceKey = process.env.SEAMLESS_SERVICE_TOKEN;
     if (!serviceKey) {
         throw new Error("Cannot sign service token. Missing SEAMLESS_SERVICE_TOKEN");
     }
@@ -8,16 +8,14 @@ export async function authFetch(req, url, { method = "POST", body, cookies, head
     // Issue short-lived machine token
     // -------------------------------
     const token = jwt.sign({
-        // Minimal, safe fields
         iss: process.env.FRONTEND_URL,
-        aud: process.env.AUTH_SERVER,
+        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" }),

package/dist/internal/cookie.d.ts

@@ -8,3 +8,4 @@ export interface CookiePayload {
 export declare function setSessionCookie(res: Response, payload: CookiePayload, domain?: string, ttlSeconds?: number, name?: string): void;
 export declare function clearSessionCookie(res: Response, domain: string, name?: string): void;
 export declare function clearAllCookies(res: Response, domain: string, accesscookieName: string, registrationCookieName: string, refreshCookieName: string): void;
+//# sourceMappingURL=cookie.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cookie.d.ts","sourceRoot":"","sources":["../../src/internal/cookie.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,aAAa,EACtB,MAAM,CAAC,EAAE,MAAM,EACf,UAAU,SAAM,EAChB,IAAI,SAAe,QAqBpB;AAED,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,QAAQ,EACb,MAAM,EAAE,MAAM,EACd,IAAI,SAAe,QAGpB;AAED,wBAAgB,eAAe,CAC7B,GAAG,EAAE,QAAQ,EACb,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,EACxB,sBAAsB,EAAE,MAAM,EAC9B,iBAAiB,EAAE,MAAM,QAK1B"}

package/dist/internal/cookie.js

@@ -1,9 +1,10 @@
 import jwt from "jsonwebtoken";
-const COOKIE_SECRET = process.env.SEAMLESS_COOKIE_SIGNING_KEY;
-if (!COOKIE_SECRET) {
-    console.warn("[SeamlessAuth] Missing SEAMLESS_COOKIE_SIGNING_KEY env var!");
-}
 export function setSessionCookie(res, payload, domain, ttlSeconds = 300, name = "sa_session") {
+    const COOKIE_SECRET = process.env.SEAMLESS_COOKIE_SIGNING_KEY;
+    if (!COOKIE_SECRET) {
+        console.warn("[SeamlessAuth] Missing SEAMLESS_COOKIE_SIGNING_KEY env var!");
+        throw new Error("Missing required env SEAMLESS_COOKIE_SIGNING_KEY");
+    }
     const token = jwt.sign(payload, COOKIE_SECRET, {
         algorithm: "HS256",
         expiresIn: `${ttlSeconds}s`,

package/dist/internal/getSeamlessUser.d.ts

@@ -1,10 +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

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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/internal/refreshAccessToken.d.ts

@@ -7,3 +7,4 @@ export declare function refreshAccessToken(req: CookieRequest, authServerUrl: st
     ttl: number;
     refreshTtl: number;
 } | null>;
+//# sourceMappingURL=refreshAccessToken.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"refreshAccessToken.d.ts","sourceRoot":"","sources":["../../src/internal/refreshAccessToken.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,gCAAgC,CAAC;AAG/D,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,aAAa,EAClB,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC;IACT,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,IAAI,CAAC,CAwDR"}

package/dist/internal/refreshAccessToken.js

@@ -1,11 +1,12 @@
 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 {
+        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 serviceKey = process.env.SEAMLESS_SERVICE_TOKEN;
         if (!serviceKey) {
             throw new Error("Cannot sign service token. Missing SEAMLESS_SERVICE_TOKEN");
         }

package/dist/internal/verifyCookieJwt.d.ts

@@ -1 +1,2 @@
 export declare function verifyCookieJwt<T = any>(token: string): T | null;
+//# sourceMappingURL=verifyCookieJwt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verifyCookieJwt.d.ts","sourceRoot":"","sources":["../../src/internal/verifyCookieJwt.ts"],"names":[],"mappings":"AAIA,wBAAgB,eAAe,CAAC,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,GAAG,IAAI,CAShE"}

package/dist/internal/verifySignedAuthResponse.d.ts

@@ -3,3 +3,4 @@
  * Uses the Auth Server's JWKS endpoint to dynamically fetch public keys.
  */
 export declare function verifySignedAuthResponse<T = any>(token: string, authServerUrl: string): Promise<T | null>;
+//# sourceMappingURL=verifySignedAuthResponse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verifySignedAuthResponse.d.ts","sourceRoot":"","sources":["../../src/internal/verifySignedAuthResponse.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,wBAAsB,wBAAwB,CAAC,CAAC,GAAG,GAAG,EACpD,KAAK,EAAE,MAAM,EACb,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAmBnB"}

package/dist/middleware/ensureCookies.d.ts

@@ -5,3 +5,4 @@ export interface CookieRequest extends Request {
     cookiePayload?: JwtPayload;
 }
 export declare function createEnsureCookiesMiddleware(opts: SeamlessAuthServerOptions): (req: CookieRequest, res: Response, next: NextFunction, cookieDomain?: string) => Promise<void | Response<any, Record<string, any>>>;
+//# sourceMappingURL=ensureCookies.d.ts.map

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

@@ -0,0 +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,wDAqFpB"}

package/dist/middleware/ensureCookies.js

@@ -1,11 +1,6 @@
 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 },
@@ -34,14 +29,9 @@ export function createEnsureCookiesMiddleware(opts) {
         if (!match)
             return next();
         const [, { name, required }] = match;
+        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");
@@ -65,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,8 +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

@@ -0,0 +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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;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

@@ -1,20 +1,68 @@
 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
+ * 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_URL;
     return async (req, res, next) => {
         try {
+            if (!COOKIE_SECRET) {
+                throw new Error("Missing required SEAMLESS_COOKIE_SIGNING_KEY env");
+            }
             const token = req.cookies?.[cookieName];
             if (!token) {
                 res.status(401).json({ error: "Missing access cookie" });

package/dist/middleware/requireRole.d.ts

@@ -1,8 +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

@@ -0,0 +1 @@
+{"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,17 +1,58 @@
 import jwt from "jsonwebtoken";
-const COOKIE_SECRET = process.env.SEAMLESS_COOKIE_SIGNING_KEY;
-if (!COOKIE_SECRET) {
-    console.warn("[PortalAPI] Missing SEAMLESS_COOKIE_SIGNING_KEY — role checks will fail.");
-}
 /**
- * Express middleware to enforce a required role from Seamless Auth cookie JWT.
+ * Express middleware that enforces role-based authorization for Seamless Auth sessions.
+ *
+ * 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
  *
- * @param role        Role name to require (e.g. 'admin')
- * @param cookieName  Cookie name containing JWT (default: 'sa_session')
+ * ### 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) => {
         try {
+            const COOKIE_SECRET = process.env.SEAMLESS_COOKIE_SIGNING_KEY;
+            if (!COOKIE_SECRET) {
+                console.warn("[SeamlessAuth] SEAMLESS_COOKIE_SIGNING_KEY missing — requireRole will always fail.");
+                throw new Error("Missing required env SEAMLESS_COOKIE_SIGNING_KEY");
+            }
             const token = req.cookies?.[cookieName];
             if (!token) {
                 res.status(401).json({ error: "Missing access cookie" });
@@ -29,7 +70,7 @@ export function requireRole(role, cookieName = "seamless-access") {
             next();
         }
         catch (err) {
-            console.error(`[PortalAPI] requireRole(${role}) failed:`, err.message);
+            console.error(`[RequireRole] requireRole(${role}) failed:`, err.message);
             res.status(401).json({ error: "Invalid or expired access cookie" });
         }
     };

package/dist/types.d.ts

@@ -6,3 +6,4 @@ export interface SeamlessAuthServerOptions {
     refreshCookieName?: string;
     preAuthCookieName?: string;
 }
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamless-auth/express",
-  "version": "0.0.1-beta.3",
+  "version": "0.0.2-beta.1",
   "description": "Express adapter for Seamless Auth passwordless authentication",
   "license": "MIT",
   "type": "module",
@@ -24,6 +24,7 @@
   },
   "dependencies": {
     "cookie-parser": "^1.4.6",
+    "dotenv": "^17.2.3",
     "jose": "^6.1.1",
     "jsonwebtoken": "^9.0.2",
     "node-fetch": "^3.3.2"