@seamless-auth/express 0.0.0

package/README.md

@@ -0,0 +1,13 @@
+# @seamless-auth/server-express
+
+Drop-in Express adapter for Seamless Auth “server mode” authentication.
+
+```js
+import express from "express";
+import createSeamlessAuthServer from "@seamless-auth/server-express";
+
+const app = express();
+app.use("/auth", createSeamlessAuthServer({
+  authServerUrl: process.env.AUTH_SERVER_URL,
+  cookieDomain: ".myapp.com"
+}));

package/dist/createServer.d.ts

@@ -0,0 +1,3 @@
+import { Router } from "express";
+import type { SeamlessAuthServerOptions } from "./types";
+export declare function createSeamlessAuthServer(opts: SeamlessAuthServerOptions): Router;

package/dist/createServer.js

@@ -0,0 +1,128 @@
+import express from "express";
+import cookieParser from "cookie-parser";
+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';
+export function createSeamlessAuthServer(opts) {
+    const r = express.Router();
+    r.use(express.json());
+    r.use(cookieParser());
+    const { authServerUrl, cookieDomain = "", accesscookieName = "seamless-auth-access", registrationCookieName = "seamless-auth-registration", refreshCookieName = "seamless-auth-refresh", preAuthCookieName = "seamless-auth-pre-auth" } = opts;
+    const proxy = (path, method = "POST") => async (req, res) => {
+        try {
+            const response = await authFetch(req, `${authServerUrl}/${path}`, { method, body: req.body });
+            res.status(response.status).json(await response.json());
+        }
+        catch (error) {
+            console.error(`Failed to proxy to route. Error: ${error}`);
+        }
+    };
+    r.use(createEnsureCookiesMiddleware({
+        authServerUrl,
+        cookieDomain,
+        accesscookieName,
+        registrationCookieName,
+        refreshCookieName,
+        preAuthCookieName
+    }));
+    r.post("/webAuthn/login/start", proxy("webAuthn/login/start"));
+    r.post("/webAuthn/login/finish", finishLogin);
+    r.get("/webAuthn/register/start", proxy("webAuthn/register/start", "GET"));
+    r.post("/webAuthn/register/finish", finishRegister);
+    r.post("/otp/verify-phone-otp", proxy("otp/verify-phone-otp"));
+    r.post("/otp/verify-email-otp", proxy("otp/verify-email-otp"));
+    r.post("/login", login);
+    r.post("/registration/register", register);
+    r.post("/logout", logout);
+    r.get("/users/me", me);
+    return r;
+    async function login(req, res) {
+        const up = await authFetch(req, `${authServerUrl}/login`, {
+            method: "POST",
+            body: req.body,
+        });
+        const data = (await up.json());
+        if (!up.ok)
+            return res.status(up.status).json(data);
+        const verified = await verifySignedAuthResponse(data.token, authServerUrl);
+        if (!verified) {
+            throw new Error("Invalid signed response from Auth Server");
+        }
+        if (verified.sub !== data.sub) {
+            throw new Error("Signature mismatch with data payload");
+        }
+        setSessionCookie(res, { sub: data.sub }, cookieDomain, data.ttl, preAuthCookieName);
+        res.status(204).end();
+    }
+    async function register(req, res) {
+        const up = await authFetch(req, `${authServerUrl}/registration/register`, {
+            method: "POST",
+            body: req.body,
+        });
+        const data = (await up.json());
+        if (!up.ok)
+            return res.status(up.status).json(data);
+        setSessionCookie(res, { sub: data.sub }, cookieDomain, data.ttl, registrationCookieName);
+        res.status(200).json(data).end();
+    }
+    async function finishLogin(req, res) {
+        const up = await authFetch(req, `${authServerUrl}/webAuthn/login/finish`, {
+            method: "POST",
+            body: req.body,
+        });
+        const data = (await up.json());
+        if (!up.ok)
+            return res.status(up.status).json(data);
+        const verifiedAccessToken = await verifySignedAuthResponse(data.token, authServerUrl);
+        const verifiedRefreshToken = await verifySignedAuthResponse(data.refreshToken, authServerUrl);
+        if (!verifiedAccessToken || !verifiedRefreshToken) {
+            throw new Error("Invalid signed response from Auth Server");
+        }
+        if (verifiedAccessToken.sub !== data.sub || verifiedRefreshToken.sub !== data.sub) {
+            throw new Error("Signature mismatch with data payload");
+        }
+        setSessionCookie(res, { sub: data.sub, roles: data.roles }, cookieDomain, data.ttl, accesscookieName);
+        setSessionCookie(res, { sub: data.sub, refreshToken: data.refreshToken }, cookieDomain, data.ttl, refreshCookieName);
+        res.status(200).json(data).end();
+    }
+    async function finishRegister(req, res) {
+        const up = await authFetch(req, `${authServerUrl}/webAuthn/register/finish`, {
+            method: "POST",
+            body: req.body,
+        });
+        const data = (await up.json());
+        if (!up.ok)
+            return res.status(up.status).json(data);
+        setSessionCookie(res, { sub: data.sub, roles: data.roles }, cookieDomain, data.ttl, accesscookieName);
+        res.status(204).end();
+    }
+    async function logout(req, res) {
+        const sid = req.cookies[accesscookieName];
+        if (sid)
+            await authFetch(req, `${authServerUrl}/logout`, {
+                method: "POST",
+                body: { sid },
+            });
+        clearAllCookies(res, cookieDomain, accesscookieName, registrationCookieName, refreshCookieName);
+        res.status(204).end();
+    }
+    async function me(req, res) {
+        const up = await authFetch(req, `${authServerUrl}/users/me`, {
+            method: "GET",
+        });
+        const data = (await up.json());
+        console.log(data.token);
+        const verified = await verifySignedAuthResponse(data.token, authServerUrl);
+        if (!verified) {
+            throw new Error("Invalid signed response from Auth Server");
+        }
+        if (verified.sub !== data.sub) {
+            throw new Error("Signature mismatch with data payload");
+        }
+        clearSessionCookie(res, cookieDomain, preAuthCookieName);
+        if (!data.user)
+            return res.status(401).json({ error: "unauthenticated" });
+        res.json({ user: data.user });
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { createSeamlessAuthServer } from "./createServer";
+export { requireAuth } from "./middleware/requireAuth";
+export { requireRole } from "./middleware/requireRole";
+export { getSeamlessUser } from "./internal/getSeamlessUser";
+export type { SeamlessAuthServerOptions } from "./types";
+export default createSeamlessAuthServer;

package/dist/index.js

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

@@ -0,0 +1,8 @@
+import { CookieRequest } from "../middleware/ensureCookies";
+export interface AuthFetchOptions {
+    method?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    body?: any;
+    cookies?: string[];
+    headers?: Record<string, string>;
+}
+export declare function authFetch(req: CookieRequest, url: string, { method, body, cookies, headers }?: AuthFetchOptions): Promise<import("node-fetch").Response>;

package/dist/internal/authFetch.js

@@ -0,0 +1,31 @@
+import fetch from "node-fetch";
+import jwt from "jsonwebtoken";
+const privateKey = process.env.SERVICE_JWT_KEY;
+export async function authFetch(req, url, { method = "POST", body, cookies, headers = {} } = {}) {
+    const token = privateKey
+        ? jwt.sign({ aud: "auth-internal", iss: "portal-api", sub: req.cookiePayload?.sub, role: req.cookiePayload?.roles }, privateKey, {
+            expiresIn: "60s",
+            keyid: "service-main",
+        })
+        : undefined;
+    if (!token) {
+        throw new Error("Cannot sign JWT for communications with Seamless Auth Server. Did you set your SERVICE_JWT_KEY?");
+    }
+    const finalHeaders = {
+        ...(method !== "GET" && { "Content-Type": "application/json" }),
+        ...(cookies ? { Cookie: cookies.join("; ") } : {}),
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+        ...headers,
+    };
+    let finalUrl = url;
+    if (method === "GET" && body && typeof body === "object") {
+        const qs = new URLSearchParams(body).toString();
+        finalUrl += url.includes("?") ? `&${qs}` : `?${qs}`;
+    }
+    const res = await fetch(finalUrl, {
+        method,
+        headers: finalHeaders,
+        ...(method !== "GET" && body ? { body: JSON.stringify(body) } : {}),
+    });
+    return res;
+}

package/dist/internal/cookie.d.ts

@@ -0,0 +1,9 @@
+import { Response } from "express";
+export interface CookiePayload {
+    sub: string;
+    refreshToken?: string;
+    roles?: string[];
+}
+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;

package/dist/internal/cookie.js

@@ -0,0 +1,27 @@
+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 token = jwt.sign(payload, COOKIE_SECRET, {
+        algorithm: "HS256",
+        expiresIn: ttlSeconds,
+    });
+    res.cookie(name, token, {
+        httpOnly: true,
+        secure: true,
+        sameSite: "lax",
+        path: "/",
+        domain,
+        maxAge: ttlSeconds * 1000,
+    });
+}
+export function clearSessionCookie(res, domain, name = "sa_session") {
+    res.clearCookie(name, { domain, path: "/" });
+}
+export function clearAllCookies(res, domain, accesscookieName, registrationCookieName, refreshCookieName) {
+    res.clearCookie(accesscookieName, { domain, path: "/" });
+    res.clearCookie(registrationCookieName, { domain, path: "/" });
+    res.clearCookie(refreshCookieName, { domain, path: "/" });
+}

package/dist/internal/getSeamlessUser.d.ts

@@ -0,0 +1,10 @@
+import type { Request } from "express";
+/**
+ * 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.
+ *
+ * @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
+ */
+export declare function getSeamlessUser<T = any>(req: Request, authServerUrl: string): Promise<T | null>;

package/dist/internal/getSeamlessUser.js

@@ -0,0 +1,34 @@
+import { authFetch } from "./authFetch.js";
+import { verifySignedAuthResponse } from "./verifySignedAuthResponse.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.
+ *
+ * @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
+ */
+export async function getSeamlessUser(req, authServerUrl) {
+    try {
+        const response = await authFetch(req, `${authServerUrl}/users/me`, {
+            method: "GET",
+        });
+        if (!response.ok) {
+            console.warn(`[SeamlessAuth] Auth server responded ${response.status}`);
+            return null;
+        }
+        const data = (await response.json());
+        const verified = await verifySignedAuthResponse(data.token, authServerUrl);
+        if (!verified) {
+            throw new Error("Invalid signed response from Auth Server");
+        }
+        if (verified.sub !== data.sub) {
+            throw new Error("Signature mismatch with data payload");
+        }
+        return data.user;
+    }
+    catch (err) {
+        console.error("[SeamlessAuth] getSeamlessUser failed:", err);
+        return null;
+    }
+}

package/dist/internal/verifyCookieJwt.d.ts

@@ -0,0 +1 @@
+export declare function verifyCookieJwt<T = any>(token: string): T | null;

package/dist/internal/verifyCookieJwt.js

@@ -0,0 +1,13 @@
+import jwt from "jsonwebtoken";
+const COOKIE_SECRET = process.env.SEAMLESS_COOKIE_SIGNING_KEY;
+export function verifyCookieJwt(token) {
+    try {
+        return jwt.verify(token, COOKIE_SECRET, {
+            algorithms: ["HS256"],
+        });
+    }
+    catch (err) {
+        console.error("[SeamlessAuth] Cookie JWT verification failed:", err);
+        return null;
+    }
+}

package/dist/internal/verifySignedAuthResponse.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Verifies a signed response JWT from a Seamless Auth server.
+ * 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>;

package/dist/internal/verifySignedAuthResponse.js

@@ -0,0 +1,22 @@
+import { createRemoteJWKSet, jwtVerify } from "jose";
+/**
+ * Verifies a signed response JWT from a Seamless Auth server.
+ * Uses the Auth Server's JWKS endpoint to dynamically fetch public keys.
+ */
+export async function verifySignedAuthResponse(token, authServerUrl) {
+    try {
+        // Construct JWKS URL from auth server
+        const jwksUrl = new URL("/.well-known/jwks.json", authServerUrl).toString();
+        // Create a remote JWKS verifier (auto-caches)
+        const JWKS = createRemoteJWKSet(new URL(jwksUrl));
+        // Verify signature and algorithm
+        const { payload } = await jwtVerify(token, JWKS, {
+            algorithms: ["RS256"],
+        });
+        return payload;
+    }
+    catch (err) {
+        console.error("[SeamlessAuth] Failed to verify signed auth response:", err);
+        return null;
+    }
+}

package/dist/middleware/ensureCookies.d.ts

@@ -0,0 +1,7 @@
+import { NextFunction, Request, Response } from "express";
+import { SeamlessAuthServerOptions } from "../types";
+import { JwtPayload } from "jsonwebtoken";
+export interface CookieRequest extends Request {
+    cookiePayload?: JwtPayload;
+}
+export declare function createEnsureCookiesMiddleware(opts: SeamlessAuthServerOptions): (req: CookieRequest, res: Response, next: NextFunction) => void | Response<any, Record<string, any>>;

package/dist/middleware/ensureCookies.js

@@ -0,0 +1,32 @@
+import { verifyCookieJwt } from "../internal/verifyCookieJwt.js";
+export function createEnsureCookiesMiddleware(opts) {
+    const COOKIE_REQUIREMENTS = {
+        "/webAuthn/login/finish": { name: opts.preAuthCookieName, required: true },
+        "/webAuthn/login/start": { name: opts.preAuthCookieName, required: true },
+        "/webAuthn/register/start": { name: opts.registrationCookieName, required: true },
+        "/webAuthn/register/finish": { name: opts.registrationCookieName, required: true },
+        "/otp/verify-email-otp": { name: opts.registrationCookieName, required: true },
+        "/otp/verify-phone-otp": { name: opts.registrationCookieName, required: true },
+        "/logout": { name: opts.accesscookieName, required: true },
+        "/users/me": { name: opts.accesscookieName, required: true },
+    };
+    return function ensureCookies(req, res, next) {
+        const match = Object.entries(COOKIE_REQUIREMENTS).find(([path]) => req.path.startsWith(path));
+        if (!match)
+            return next();
+        const [, { name, required }] = match;
+        const cookieValue = req.cookies?.[name];
+        if (required && !cookieValue) {
+            return res.status(400).json({
+                error: `Missing required cookie "${name}" for route ${req.path}`,
+                hint: "Did you forget to call /auth/login/start first?",
+            });
+        }
+        const payload = verifyCookieJwt(cookieValue);
+        if (!payload) {
+            return res.status(401).json({ error: `Invalid or expired ${name} cookie` });
+        }
+        req.cookiePayload = payload;
+        next();
+    };
+}

package/dist/middleware/requireAuth.d.ts

@@ -0,0 +1,8 @@
+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
+ */
+export declare function requireAuth(cookieName?: string): (req: Request, res: Response, next: NextFunction) => void;

package/dist/middleware/requireAuth.js

@@ -0,0 +1,33 @@
+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.");
+}
+/**
+ * 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
+ */
+export function requireAuth(cookieName = "seamless-auth-access") {
+    return (req, res, next) => {
+        try {
+            const token = req.cookies?.[cookieName];
+            if (!token) {
+                res.status(401).json({ error: "Missing access cookie" });
+                return;
+            }
+            const payload = jwt.verify(token, COOKIE_SECRET, {
+                algorithms: ["HS256"],
+            });
+            // Attach decoded JWT claims to request for downstream handlers
+            req.user = payload;
+            next();
+        }
+        catch (err) {
+            console.error("[SeamlessAuth] requireAuth error:", err.message);
+            res.status(401).json({ error: "Invalid or expired access cookie" });
+            return;
+        }
+    };
+}

package/dist/middleware/requireRole.d.ts

@@ -0,0 +1,8 @@
+import { RequestHandler } from "express";
+/**
+ * Express middleware to enforce a required role from Seamless Auth cookie JWT.
+ *
+ * @param role        Role name to require (e.g. 'admin')
+ * @param cookieName  Cookie name containing JWT (default: 'sa_session')
+ */
+export declare function requireRole(role: string, cookieName?: string): RequestHandler;

package/dist/middleware/requireRole.js

@@ -0,0 +1,36 @@
+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.
+ *
+ * @param role        Role name to require (e.g. 'admin')
+ * @param cookieName  Cookie name containing JWT (default: 'sa_session')
+ */
+export function requireRole(role, cookieName = "seamless-auth-access") {
+    return (req, res, next) => {
+        try {
+            const token = req.cookies?.[cookieName];
+            if (!token) {
+                res.status(401).json({ error: "Missing access cookie" });
+                return;
+            }
+            // Verify JWT signature
+            const payload = jwt.verify(token, COOKIE_SECRET, {
+                algorithms: ["HS256"],
+            });
+            // Check role membership
+            if (!payload.roles?.includes(role)) {
+                res.status(403).json({ error: `Forbidden: ${role} role required` });
+                return;
+            }
+            next();
+        }
+        catch (err) {
+            console.error(`[PortalAPI] requireRole(${role}) failed:`, err.message);
+            res.status(401).json({ error: "Invalid or expired access cookie" });
+        }
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,8 @@
+export interface SeamlessAuthServerOptions {
+    authServerUrl: string;
+    cookieDomain?: string;
+    accesscookieName?: string;
+    registrationCookieName?: string;
+    refreshCookieName?: string;
+    preAuthCookieName?: string;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@seamless-auth/express",
+  "version": "0.0.0",
+  "description": "Express adapter for Seamless Auth passwordless authentication",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "./dist/index.d.ts",
+  "author": "Fells Code LLC",
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node build.mjs",
+    "dev": "tsc --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fells-code/seamless-auth-server"
+  },
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@types/express": ">=5.0.0",
+    "express": ">=5.1.0"
+  },
+  "dependencies": {
+    "cookie-parser": "^1.4.6",
+    "jose": "^6.1.1",
+    "jsonwebtoken": "^9.0.2",
+    "node-fetch": "^3.3.2",
+    "version-packages": "changeset version",
+    "release": "changeset publish"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.29.7",
+    "@types/cookie-parser": "^1.4.10",
+    "@types/jsonwebtoken": "^9.0.10",
+    "typescript": "^5.5.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}