@seamless-auth/express 0.0.2-beta.6 → 0.0.2-beta.7

package/dist/index.d.ts

@@ -0,0 +1,213 @@
+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",
+ *   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.
+ */
+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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamless-auth/express",
-  "version": "0.0.2-beta.6",
+  "version": "0.0.2-beta.7",
   "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": {