@seamless-auth/express 0.0.4-beta.0 → 0.1.0

package/README.md

@@ -110,14 +110,17 @@ This keeps trust boundaries clean and auditable.
 
 ## Environment Variables
 
-| Variable             | Description                               | Example                                                |
-| -------------------- | ----------------------------------------- | ------------------------------------------------------ |
-| `AUTH_SERVER_URL`    | Base URL of your Seamless Auth Server     | `https://auth.client.com`                              |
-| `COOKIE_SIGNING_KEY` | Secret for signing API session cookies    | `local-dev-secret`                                     |
-| `API_SERVICE_TOKEN`  | API → Auth Server service secret          | `shared-m2m-value`                                     |
-| `APP_ORIGIN`         | Your site URL (or localhost in demo mode) | `https://myapp.com`                                    |
-| `DATABASE_URL`       | Database URL for your API                 | `postgres://myuser:mypassword@localhost:5432/seamless` |
-| `DB_NAME`            | Name of your database                     | `seamless`                                             |
+| Variable             | Description                               | Example                   |
+| -------------------- | ----------------------------------------- | ------------------------- |
+| `AUTH_SERVER_URL`    | Base URL of your Seamless Auth Server     | `https://auth.client.com` |
+| `COOKIE_SIGNING_KEY` | Secret for signing API session cookies    | `local-dev-secret`        |
+| `API_SERVICE_TOKEN`  | API → Auth Server service secret          | `shared-m2m-value`        |
+| `APP_ORIGIN`         | Your site URL (or localhost in demo mode) | `https://myapp.com`       |
+| `DB_HOST`            | Database Host                             | `localhost`               |
+| `DB_PORT`            | Database Port                             | `5432`                    |
+| `DB_USER`            | Database user                             | `myuser`                  |
+| `DB_PASSWORD`        | Database password                         | `mypassword`              |
+| `DB_NAME`            | Name of your database                     | `seamless`                |
 
 ---
 
@@ -219,7 +222,7 @@ Returned shape (example):
 AUTH_SERVER_URL=http://localhost:5312
 SEAMLESS_SERVICE_TOKEN=generated-secret
 COOKIE_SIGNING_KEY=local-dev-key
-FRONTEND_URL=https://localhost:5001
+FRONTEND_URL=http://localhost:5001
 ```
 
 ---

package/dist/index.d.ts

@@ -1,15 +1,27 @@
 import { Router, Request, Response, NextFunction, RequestHandler } from 'express';
-import { JwtPayload } from 'jsonwebtoken';
 
-interface SeamlessAuthServerOptions {
+type SeamlessAuthServerOptions = {
     authServerUrl: string;
+    cookieSecret: string;
+    serviceSecret: string;
+    issuer: string;
+    audience: string;
+    jwksKid?: string;
     cookieDomain?: string;
     accessCookieName?: string;
     registrationCookieName?: string;
     refreshCookieName?: string;
     preAuthCookieName?: string;
+};
+interface SeamlessAuthUser {
+    id: string;
+    sub: string;
+    roles: string[];
+    email: string;
+    phone: string;
+    iat?: number;
+    exp?: number;
 }
-
 /**
  * Creates an Express Router that proxies all authentication traffic to a Seamless Auth server.
  *
@@ -38,6 +50,9 @@ interface SeamlessAuthServerOptions {
  * app.use("/auth", createSeamlessAuthServer({
  *   authServerUrl: "https://identifier.seamlessauth.com",
  *   cookieDomain: "mycompany.com",
+ *   cookieSecret: "someLongRandomValue"
+ *   serviceSecret: "someLongRandomValueToo"
+ *   jwksKid: "dev-main"
  *   accessCookieName: "sa_access",
  *   registrationCookieName: "sa_registration",
  *   refreshCookieName: "sa_refresh",
@@ -46,6 +61,9 @@ interface SeamlessAuthServerOptions {
  *
  * @param opts - Configuration options for the Seamless Auth proxy:
  *   - `authServerUrl` — Base URL of your Seamless Auth instance (required)
+ *   - `cookieSecret` — The value to encode your cookies secrets with (required)
+ *   - `serviceSecret` - An machine to machine shared secret that matches your auth servers (required)
+ *   - `jwksKid` - The active jwks KID
  *   - `cookieDomain` — Domain attribute applied to all auth cookies
  *   - `accessCookieName` — Name of the session access cookie
  *   - `registrationCookieName` — Name of the ephemeral registration cookie
@@ -56,6 +74,10 @@ interface SeamlessAuthServerOptions {
  */
 declare function createSeamlessAuthServer(opts: SeamlessAuthServerOptions): Router;
 
+interface RequireAuthOptions {
+    cookieName?: string;
+    cookieSecret: string;
+}
 /**
  * Express middleware that enforces authentication using Seamless Auth cookies.
  *
@@ -106,9 +128,6 @@ declare function createSeamlessAuthServer(opts: SeamlessAuthServerOptions): Rout
  * @returns An Express middleware function that enforces Seamless Auth
  *          authentication on incoming requests.
  */
-interface AuthenticatedRequest extends Request {
-    user?: JwtPayload;
-}
 interface RequireAuthOptions {
     cookieName?: string;
     cookieSecret: string;
@@ -121,32 +140,22 @@ interface RequireAuthOptions {
  * - This middleware does NOT attempt token refresh.
  * - Refresh is handled upstream by ensureCookies().
  */
-declare function requireAuth(opts: RequireAuthOptions): (req: AuthenticatedRequest, res: Response, next: NextFunction) => void;
+declare function requireAuth(opts: RequireAuthOptions): (req: Request, res: Response, next: NextFunction) => void;
 
 /**
- * Express middleware that enforces role-based authorization for Seamless Auth sessions.
+ * Express middleware that enforces role-based authorization for Seamless Auth.
  *
- * 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).
+ * This middleware assumes `requireAuth()` has already:
+ * - authenticated the request
+ * - populated `req.user` with the authenticated session payload
  *
- * If the user possesses the required authorization, the request proceeds.
- * Otherwise, the middleware responds with a 403 Forbidden error.
+ * `requireRole` performs **authorization only**. It does not inspect cookies,
+ * verify tokens, or read environment variables.
  *
- * ### 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
+ * If any of the required roles are present on the user, access is granted.
+ * Otherwise, a 403 Forbidden response is returned.
  *
- * ### 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
+ *  * ### Example
  * ```ts
  * // Require a single role
  * app.get("/admin/users",
@@ -163,13 +172,10 @@ declare function requireAuth(opts: RequireAuthOptions): (req: AuthenticatedReque
  *   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.
+ * @param requiredRoles - A role or list of roles required to access the route
  */
-declare function requireRole(role: string, cookieName?: string): RequestHandler;
+declare function requireRole(requiredRoles: string | string[]): RequestHandler;
 
 interface EnsureCookiesMiddlewareOptions {
     authServerUrl: string;
@@ -184,10 +190,8 @@ interface EnsureCookiesMiddlewareOptions {
     audience: string;
     keyId: string;
 }
-declare function createEnsureCookiesMiddleware(opts: EnsureCookiesMiddlewareOptions): (req: Request & {
-    cookiePayload?: any;
-}, res: Response, next: NextFunction) => Promise<void>;
+declare function createEnsureCookiesMiddleware(opts: EnsureCookiesMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
 
-declare function getSeamlessUser<T = any>(req: Request, authServerUrl: string, cookieName?: string): Promise<T | null>;
+declare function getSeamlessUser(req: Request, opts: SeamlessAuthServerOptions): Promise<any>;
 
-export { type SeamlessAuthServerOptions, createEnsureCookiesMiddleware, createSeamlessAuthServer as default, getSeamlessUser, requireAuth, requireRole };
+export { type SeamlessAuthServerOptions, type SeamlessAuthUser, createEnsureCookiesMiddleware, createSeamlessAuthServer as default, getSeamlessUser, requireAuth, requireRole };

package/dist/index.js

@@ -98,7 +98,7 @@ function applyResult(res, req, result, opts, cookieSigner) {
 import { loginHandler } from "@seamless-auth/core/handlers/login";
 async function login(req, res, opts) {
   const cookieSigner = {
-    secret: process.env.COOKIE_SIGNING_KEY,
+    secret: opts.cookieSecret,
     secure: process.env.NODE_ENV === "production",
     sameSite: process.env.NODE_ENV === "production" ? "none" : "lax"
   };
@@ -138,16 +138,16 @@ import { finishLoginHandler } from "@seamless-auth/core/handlers/finishLogin";
 
 // src/internal/buildAuthorization.ts
 import { createServiceToken } from "@seamless-auth/core";
-function buildServiceAuthorization(req) {
-  if (!req.cookiePayload?.sub) {
+function buildServiceAuthorization(req, opts) {
+  if (!req.cookiePayload?.sub && !req.user.sub) {
     return void 0;
   }
   const token = createServiceToken({
-    subject: req.cookiePayload.sub,
-    issuer: process.env.APP_ORIGIN,
-    audience: process.env.AUTH_SERVER_URL,
-    serviceSecret: process.env.API_SERVICE_TOKEN,
-    keyId: "dev-main"
+    subject: req.cookiePayload?.sub || req.user.sub,
+    issuer: opts.issuer,
+    audience: opts.audience,
+    serviceSecret: opts.serviceSecret,
+    keyId: opts.jwksKid || "dev-main"
   });
   return `Bearer ${token}`;
 }
@@ -155,11 +155,11 @@ function buildServiceAuthorization(req) {
 // src/handlers/finishLogin.ts
 async function finishLogin(req, res, opts) {
   const cookieSigner = {
-    secret: process.env.COOKIE_SIGNING_KEY,
+    secret: opts.cookieSecret,
     secure: process.env.NODE_ENV === "production",
     sameSite: process.env.NODE_ENV === "production" ? "none" : "lax"
   };
-  const authorization = buildServiceAuthorization(req);
+  const authorization = buildServiceAuthorization(req, opts);
   const result = await finishLoginHandler(
     { body: req.body, authorization },
     {
@@ -196,7 +196,7 @@ async function finishLogin(req, res, opts) {
 import { registerHandler } from "@seamless-auth/core/handlers/register";
 async function register(req, res, opts) {
   const cookieSigner = {
-    secret: process.env.COOKIE_SIGNING_KEY,
+    secret: opts.cookieSecret,
     secure: process.env.NODE_ENV === "production",
     sameSite: process.env.NODE_ENV === "production" ? "none" : "lax"
   };
@@ -235,11 +235,11 @@ async function register(req, res, opts) {
 import { finishRegisterHandler } from "@seamless-auth/core/handlers/finishRegister";
 async function finishRegister(req, res, opts) {
   const cookieSigner = {
-    secret: process.env.COOKIE_SIGNING_KEY,
+    secret: opts.cookieSecret,
     secure: process.env.NODE_ENV === "production",
     sameSite: process.env.NODE_ENV === "production" ? "none" : "lax"
   };
-  const authorization = buildServiceAuthorization(req);
+  const authorization = buildServiceAuthorization(req, opts);
   const result = await finishRegisterHandler(
     { body: req.body, authorization },
     {
@@ -269,13 +269,13 @@ async function finishRegister(req, res, opts) {
   if (result.error) {
     return res.status(result.status).json(result.error);
   }
-  res.status(result.status).end();
+  res.status(result.status).json({ message: "success" });
 }
 
 // src/handlers/me.ts
 import { meHandler } from "@seamless-auth/core/handlers/me";
 async function me(req, res, opts) {
-  const authorization = buildServiceAuthorization(req);
+  const authorization = buildServiceAuthorization(req, opts);
   const result = await meHandler({
     authServerUrl: opts.authServerUrl,
     preAuthCookieName: opts.preAuthCookieName,
@@ -305,10 +305,50 @@ async function logout(req, res, opts) {
   res.status(result.status).end();
 }
 
+// src/handlers/pollMagicLinkConfirmation.ts
+import { pollMagicLinkConfirmationHandler } from "@seamless-auth/core/handlers/pollMagicLinkConfirmationHandler";
+async function pollMagicLinkConfirmation(req, res, opts) {
+  const cookieSigner = {
+    secret: opts.cookieSecret,
+    secure: process.env.NODE_ENV === "production",
+    sameSite: process.env.NODE_ENV === "production" ? "none" : "lax"
+  };
+  const authorization = buildServiceAuthorization(req, opts);
+  const result = await pollMagicLinkConfirmationHandler(
+    { authorization },
+    {
+      authServerUrl: opts.authServerUrl,
+      cookieDomain: opts.cookieDomain,
+      accessCookieName: opts.accessCookieName,
+      refreshCookieName: opts.refreshCookieName
+    }
+  );
+  if (!cookieSigner.secret) {
+    throw new Error("Missing COOKIE_SIGNING_KEY");
+  }
+  if (result.setCookies) {
+    for (const c of result.setCookies) {
+      setSessionCookie(
+        res,
+        {
+          name: c.name,
+          payload: c.value,
+          domain: c.domain,
+          ttlSeconds: c.ttl
+        },
+        cookieSigner
+      );
+    }
+  }
+  if (result.error) {
+    return res.status(result.status).json(result.error);
+  }
+  res.status(result.status).json(result.body).end();
+}
+
 // src/createServer.ts
 import {
-  authFetch,
-  createServiceToken as createServiceToken2
+  authFetch
 } from "@seamless-auth/core";
 function createSeamlessAuthServer(opts) {
   const r = express.Router();
@@ -316,6 +356,11 @@ function createSeamlessAuthServer(opts) {
   r.use(cookieParser());
   const resolvedOpts = {
     authServerUrl: opts.authServerUrl,
+    issuer: opts.issuer,
+    audience: opts.audience,
+    cookieSecret: opts.cookieSecret,
+    serviceSecret: opts.serviceSecret,
+    jwksKid: opts.jwksKid ?? "dev-main",
     cookieDomain: opts.cookieDomain ?? "",
     accessCookieName: opts.accessCookieName ?? "seamless-access",
     registrationCookieName: opts.registrationCookieName ?? "seamless-ephemeral",
@@ -339,14 +384,11 @@ function createSeamlessAuthServer(opts) {
       res.status(401).json({ error: "registeration session required" });
       return;
     }
-    const authorization = buildServiceAuthorization2(req);
+    const authorization = buildServiceAuthorization(req, resolvedOpts);
+    const options = method == "GET" ? { method, authorization } : { method, authorization, body: req.body };
     const upstream = await authFetch(
       `${resolvedOpts.authServerUrl}/${path}`,
-      {
-        method,
-        body: req.body,
-        authorization
-      }
+      options
     );
     const data = await upstream.json();
     res.status(upstream.status).json(data);
@@ -359,26 +401,13 @@ function createSeamlessAuthServer(opts) {
       registrationCookieName: resolvedOpts.registrationCookieName,
       refreshCookieName: resolvedOpts.refreshCookieName,
       preAuthCookieName: resolvedOpts.preAuthCookieName,
-      cookieSecret: process.env.COOKIE_SIGNING_KEY,
-      serviceSecret: process.env.API_SERVICE_TOKEN,
-      issuer: process.env.APP_ORIGIN,
-      audience: process.env.AUTH_SERVER_URL,
-      keyId: "dev-main"
+      cookieSecret: resolvedOpts.cookieSecret,
+      serviceSecret: resolvedOpts.serviceSecret,
+      issuer: resolvedOpts.issuer,
+      audience: resolvedOpts.authServerUrl,
+      keyId: resolvedOpts.jwksKid
     })
   );
-  function buildServiceAuthorization2(req) {
-    if (!req.cookiePayload?.sub) {
-      return void 0;
-    }
-    const token = createServiceToken2({
-      subject: req.cookiePayload.sub,
-      issuer: process.env.APP_ORIGIN,
-      audience: process.env.AUTH_SERVER_URL,
-      serviceSecret: process.env.API_SERVICE_TOKEN,
-      keyId: "dev-main"
-    });
-    return `Bearer ${token}`;
-  }
   r.post(
     "/webAuthn/login/start",
     proxyWithIdentity("webAuthn/login/start", "preAuth")
@@ -419,6 +448,19 @@ function createSeamlessAuthServer(opts) {
     "/users/credentials",
     proxyWithIdentity("users/credentials", "access")
   );
+  r.get("/magic-link", proxyWithIdentity("magic-link", "preAuth", "GET"));
+  r.get("/magic-link/verify/:token", async (req, res) => {
+    const upstream = await authFetch(
+      `${resolvedOpts.authServerUrl}/magic-link/verify/${req.params.token}`,
+      { method: "GET" }
+    );
+    const data = await upstream.json();
+    res.status(upstream.status).json(data);
+  });
+  r.get(
+    "/magic-link/check",
+    (req, res) => pollMagicLinkConfirmation(req, res, resolvedOpts)
+  );
   return r;
 }
 
@@ -432,58 +474,78 @@ function requireAuth(opts) {
   return function(req, res, next) {
     const token = req.cookies?.[cookieName];
     if (!token) {
-      res.status(401).json({ error: "Missing access cookie" });
+      console.error(
+        "[SEAMLESS-AUTH-EXPRESS] - (requireAuth) - Missing expected cookie. Ensure you are using `cookieParser` in your express server",
+        cookieName
+      );
+      res.status(401).json({
+        error: "Failed to find authentication token required"
+      });
       return;
     }
     const payload = verifyCookieJwt(token, cookieSecret);
-    if (!payload) {
-      res.status(401).json({ error: "Invalid or expired access cookie" });
+    if (!payload || !payload.sub) {
+      res.status(401).json({
+        error: "Invalid or expired session"
+      });
       return;
     }
-    req.user = payload;
+    const user = {
+      id: payload.sub,
+      sub: payload.sub,
+      // TODO: Silly to store the same value twice. Search every where its used and phase this out.
+      roles: Array.isArray(payload.roles) ? payload.roles : [],
+      email: payload.email,
+      phone: payload.phone,
+      iat: payload.iat,
+      exp: payload.exp
+    };
+    req.user = user;
     next();
   };
 }
 
 // src/middleware/requireRole.ts
-import jwt2 from "jsonwebtoken";
-function requireRole(role, cookieName = "seamless-access") {
+function requireRole(requiredRoles) {
+  const roles = Array.isArray(requiredRoles) ? requiredRoles : [requiredRoles];
   return (req, res, next) => {
-    try {
-      const COOKIE_SECRET = process.env.COOKIE_SIGNING_KEY;
-      if (!COOKIE_SECRET) {
-        console.warn(
-          "[SeamlessAuth] COOKIE_SIGNING_KEY missing \u2014 requireRole will always fail."
-        );
-        throw new Error("Missing required env COOKIE_SIGNING_KEY");
-      }
-      const token = req.cookies?.[cookieName];
-      if (!token) {
-        res.status(401).json({ error: "Missing access cookie" });
-        return;
-      }
-      const payload = jwt2.verify(token, COOKIE_SECRET, {
-        algorithms: ["HS256"]
+    const user = req.user;
+    if (!user) {
+      res.status(401).json({
+        error: "Authentication required"
       });
-      if (!payload.roles?.includes(role)) {
-        res.status(403).json({ error: `Forbidden: ${role} role required` });
-        return;
-      }
-      next();
-    } catch (err) {
-      console.error(`[RequireRole] requireRole(${role}) failed:`, err.message);
-      res.status(401).json({ error: "Invalid or expired access cookie" });
+      return;
+    }
+    if (!Array.isArray(user.roles)) {
+      res.status(403).json({
+        error: "User has no roles assigned"
+      });
+      return;
     }
+    const hasRole = roles.some((role) => user.roles.includes(role));
+    if (!hasRole) {
+      res.status(403).json({
+        error: "Insufficient role",
+        required: roles,
+        actual: user.roles
+      });
+      return;
+    }
+    next();
   };
 }
 
 // src/getSeamlessUser.ts
-import { getSeamlessUser as getSeamlessUserCore } from "@seamless-auth/core";
-async function getSeamlessUser(req, authServerUrl, cookieName = "seamless-access") {
+import {
+  getSeamlessUser as getSeamlessUserCore
+} from "@seamless-auth/core";
+async function getSeamlessUser(req, opts) {
+  const authorization = buildServiceAuthorization(req, opts);
   return getSeamlessUserCore(req.cookies ?? {}, {
-    authServerUrl,
-    cookieSecret: process.env.COOKIE_SIGNING_KEY,
-    cookieName
+    authServerUrl: opts.authServerUrl,
+    cookieSecret: opts.cookieSecret,
+    cookieName: opts.accessCookieName ?? "seamless-access",
+    authorization
   });
 }
 

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "@seamless-auth/express",
-  "version": "0.0.4-beta.0",
+  "version": "0.1.0",
   "description": "Express adapter for Seamless Auth passwordless authentication",
   "license": "AGPL-3.0-only",
   "type": "module",
   "main": "dist/index.js",
   "types": "./dist/index.d.ts",
-  "author": "Fells Code LLC",
+  "author": "Fells Code, LLC",
   "files": [
     "dist",
     "LICENSE",
@@ -33,11 +33,11 @@
     "url": "https://github.com/fells-code/seamless-auth-server/tree/main/packages/express"
   },
   "peerDependencies": {
-    "express": ">=4.18.0",
-    "@types/express": ">=4.17.0"
+    "@types/express": ">=4.17.0",
+    "express": ">=4.18.0"
   },
   "dependencies": {
-    "@seamless-auth/core": "^0.1.0",
+    "@seamless-auth/core": "^0.2.0",
     "cookie-parser": "^1.4.6",
     "jsonwebtoken": "^9.0.3"
   },
@@ -46,8 +46,8 @@
     "@types/jest": "^29.5.14",
     "@types/jsonwebtoken": "^9.0.10",
     "jest": "^29.7.0",
-    "ts-node": "^10.9.2",
     "supertest": "^7.2.2",
+    "ts-node": "^10.9.2",
     "tsup": "^8.5.1",
     "typescript": "^5.5.0"
   },