@seamless-auth/express 0.0.2-beta.2 → 0.0.2-beta.4

package/dist/index.d.ts

@@ -0,0 +1,211 @@
+import { Router, Request, Response, NextFunction, RequestHandler } from 'express';
+import { JwtPayload } from 'jsonwebtoken';
+
+interface SeamlessAuthServerOptions {
+    authServerUrl: string;
+    cookieDomain?: string;
+    accesscookieName?: string;
+    registrationCookieName?: string;
+    refreshCookieName?: string;
+    preAuthCookieName?: string;
+}
+
+/**
+ * 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",
+ *   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)
+ *   - `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.
+ */
+declare function createSeamlessAuthServer(opts: SeamlessAuthServerOptions): Router;
+
+/**
+ * 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.
+ */
+declare function requireAuth(cookieName?: string, refreshCookieName?: string, cookieDomain?: string): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+
+/**
+ * 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
+ *
+ * ### 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.
+ */
+declare function requireRole(role: string, cookieName?: string): RequestHandler;
+
+interface CookieRequest extends Request {
+    cookiePayload?: JwtPayload;
+}
+
+/**
+ * Retrieves the authenticated Seamless Auth user for a request by calling
+ * the upstream Seamless Auth Server’s introspection endpoint.
+ *
+ * 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.
+ */
+declare function getSeamlessUser<T = any>(req: CookieRequest, authServerUrl: string, cookieName?: string): Promise<T | null>;
+
+export { type SeamlessAuthServerOptions, createSeamlessAuthServer as default, getSeamlessUser, requireAuth, requireRole };

package/dist/index.js

@@ -4,7 +4,7 @@ import cookieParser from "cookie-parser";
 
 // src/internal/cookie.ts
 import jwt from "jsonwebtoken";
-function setSessionCookie(res, payload, domain, ttlSeconds = 300, name = "sa_session") {
+function setSessionCookie(res, payload, ttlSeconds = 300, name = "sa_session") {
   const COOKIE_SECRET2 = process.env.SEAMLESS_COOKIE_SIGNING_KEY;
   if (!COOKIE_SECRET2) {
     console.warn("[SeamlessAuth] Missing SEAMLESS_COOKIE_SIGNING_KEY env var!");
@@ -19,17 +19,16 @@ function setSessionCookie(res, payload, domain, ttlSeconds = 300, name = "sa_ses
     secure: process.env.NODE_ENV === "production",
     sameSite: process.env.NODE_ENV === "production" ? "none" : "lax",
     path: "/",
-    domain,
     maxAge: ttlSeconds * 1e3
   });
 }
 function clearSessionCookie(res, domain, name = "sa_session") {
   res.clearCookie(name, { domain, path: "/" });
 }
-function clearAllCookies(res, domain, accesscookieName, registrationCookieName, refreshCookieName) {
-  res.clearCookie(accesscookieName, { domain, path: "/" });
-  res.clearCookie(registrationCookieName, { domain, path: "/" });
-  res.clearCookie(refreshCookieName, { domain, path: "/" });
+function clearAllCookies(res, accesscookieName, registrationCookieName, refreshCookieName) {
+  res.clearCookie(accesscookieName, { path: "/" });
+  res.clearCookie(registrationCookieName, { path: "/" });
+  res.clearCookie(refreshCookieName, { path: "/" });
 }
 
 // src/internal/authFetch.ts
@@ -192,7 +191,6 @@ function createEnsureCookiesMiddleware(opts) {
         if (!refreshed?.token) {
           clearAllCookies(
             res,
-            cookieDomain,
             name,
             opts.registrationCookieName,
             opts.refreshCookieName
@@ -207,14 +205,12 @@ function createEnsureCookiesMiddleware(opts) {
             token: refreshed.token,
             roles: refreshed.roles
           },
-          cookieDomain,
           refreshed.ttl,
           name
         );
         setSessionCookie(
           res,
           { sub: refreshed.sub, refreshToken: refreshed.refreshToken },
-          cookieDomain,
           refreshed.refreshTtl,
           opts.refreshCookieName
         );
@@ -264,7 +260,6 @@ function createSeamlessAuthServer(opts) {
   r.use(cookieParser());
   const {
     authServerUrl,
-    cookieDomain = "",
     accesscookieName = "seamless-access",
     registrationCookieName = "seamless-ephemeral",
     refreshCookieName = "seamless-refresh",
@@ -284,7 +279,6 @@ function createSeamlessAuthServer(opts) {
   r.use(
     createEnsureCookiesMiddleware({
       authServerUrl,
-      cookieDomain,
       accesscookieName,
       registrationCookieName,
       refreshCookieName,
@@ -317,13 +311,7 @@ function createSeamlessAuthServer(opts) {
     if (verified.sub !== data.sub) {
       throw new Error("Signature mismatch with data payload");
     }
-    setSessionCookie(
-      res,
-      { sub: data.sub },
-      cookieDomain,
-      data.ttl,
-      preAuthCookieName
-    );
+    setSessionCookie(res, { sub: data.sub }, data.ttl, preAuthCookieName);
     res.status(204).end();
   }
   async function register(req, res) {
@@ -333,13 +321,7 @@ function createSeamlessAuthServer(opts) {
     });
     const data = await up.json();
     if (!up.ok) return res.status(up.status).json(data);
-    setSessionCookie(
-      res,
-      { sub: data.sub },
-      cookieDomain,
-      data.ttl,
-      registrationCookieName
-    );
+    setSessionCookie(res, { sub: data.sub }, data.ttl, registrationCookieName);
     res.status(200).json(data).end();
   }
   async function finishLogin(req, res) {
@@ -362,14 +344,12 @@ function createSeamlessAuthServer(opts) {
     setSessionCookie(
       res,
       { sub: data.sub, roles: data.roles },
-      cookieDomain,
       data.ttl,
       accesscookieName
     );
     setSessionCookie(
       res,
       { sub: data.sub, refreshToken: data.refreshToken },
-      req.hostname,
       data.refreshTtl,
       refreshCookieName
     );
@@ -389,7 +369,6 @@ function createSeamlessAuthServer(opts) {
     setSessionCookie(
       res,
       { sub: data.sub, roles: data.roles },
-      cookieDomain,
       data.ttl,
       accesscookieName
     );
@@ -401,7 +380,6 @@ function createSeamlessAuthServer(opts) {
     });
     clearAllCookies(
       res,
-      cookieDomain,
       accesscookieName,
       registrationCookieName,
       refreshCookieName
@@ -413,7 +391,7 @@ function createSeamlessAuthServer(opts) {
       method: "GET"
     });
     const data = await up.json();
-    clearSessionCookie(res, cookieDomain, preAuthCookieName);
+    clearSessionCookie(res, preAuthCookieName);
     if (!data.user) return res.status(401).json({ error: "unauthenticated" });
     res.json({ user: data.user });
   }
@@ -474,14 +452,12 @@ function requireAuth(cookieName = "seamless-access", refreshCookieName = "seamle
             token: refreshed.token,
             roles: refreshed.roles
           },
-          cookieDomain,
           refreshed.ttl,
           cookieName
         );
         setSessionCookie(
           res,
           { sub: refreshed.sub, refreshToken: refreshed.refreshToken },
-          req.hostname,
           refreshed.refreshTtl,
           refreshCookieName
         );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamless-auth/express",
-  "version": "0.0.2-beta.2",
+  "version": "0.0.2-beta.4",
   "description": "Express adapter for Seamless Auth passwordless authentication",
   "license": "MIT",
   "type": "module",
@@ -8,7 +8,7 @@
   "types": "./dist/index.d.ts",
   "author": "Fells Code LLC",
   "scripts": {
-    "build": "tsup src/index.ts --format esm --out-dir dist --splitting",
+    "build": "tsup src/index.ts --format esm --out-dir dist --dts --splitting",
     "dev": "tsc --watch"
   },
   "repository": {