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

package/LICENSE

@@ -0,0 +1,79 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc.
+<https://fsf.org/>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+This license is identical to the GNU General Public License, except that it also
+ensures that software running as a network service makes its source code
+available to users.
+
+---
+
+TERMS AND CONDITIONS
+
+0. Definitions.
+
+“This License” refers to version 3 of the GNU Affero General Public License.
+
+“Copyright” also means copyright-like laws that apply to other kinds of works,
+such as semiconductor masks.
+
+The “Program” refers to any copyrightable work licensed under this License.
+Each licensee is addressed as “you”.
+
+To “modify” a work means to copy from or adapt all or part of the work in a
+fashion requiring copyright permission, other than the making of an exact copy.
+
+To “propagate” a work means to do anything with it that, without permission,
+would make you directly or secondarily liable for infringement under applicable
+copyright law, except executing it on a computer or modifying a private copy.
+
+To “convey” a work means any kind of propagation that enables other parties to
+make or receive copies.
+
+An interactive user interface displays “Appropriate Legal Notices” to the extent
+that it includes a convenient and prominently visible feature that displays an
+appropriate copyright notice, and tells the user that there is no warranty for
+the work (except to the extent that warranties are provided), that licensees may
+convey the work under this License, and how to view a copy of this License.
+
+---
+
+13. Remote Network Interaction; Use with the GNU General Public License.
+
+Notwithstanding any other provision of this License, if you modify the Program,
+your modified version must prominently offer all users interacting with it
+remotely through a computer network an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source from a
+network server at no charge, through some standard or customary means of
+facilitating copying of software.
+
+---
+
+15. Disclaimer of Warranty.
+
+THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.
+EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER
+PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER
+EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
+
+---
+
+16. Limitation of Liability.
+
+IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY
+COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS THE PROGRAM AS
+PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
+INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
+THE PROGRAM.
+
+---
+
+END OF TERMS AND CONDITIONS
+
+You should have received a copy of the GNU Affero General Public License along
+with this program. If not, see <https://www.gnu.org/licenses/>.

package/LICENSE.md

@@ -0,0 +1,26 @@
+# License
+
+Seamless Auth Server - Express ("@seamlessauth/express") is licensed under the **GNU Affero General Public License v3.0 (AGPL-3.0-only)**.
+
+- SPDX: `AGPL-3.0-only`
+
+## What this means (high level)
+
+- You are free to **use**, **modify**, and **self-host** this software.
+- If you **modify** this software and **run it as a network service** (for example, hosting it for others to use), you must **make the complete corresponding source code of your modified version available** to users of that service, under the AGPL.
+
+This summary is not legal advice and does not replace the license text.
+
+## Full license text
+
+The full license text is available here:
+
+- https://www.gnu.org/licenses/agpl-3.0.html
+
+You should include a copy of the AGPLv3 license in your distribution. If this repository does not contain the full license text yet, add it as `LICENSE` or `LICENSE.txt` (recommended), and keep this `LICENSE.md` as the human-friendly summary.
+
+## Commercial licensing
+
+If you would like to embed Seamless Auth API into a proprietary product, redistribute it under different terms, or offer it as a managed service without AGPL obligations, commercial licensing may be available.
+
+Contact: support@seamlessauth.com

package/README.md

@@ -1,78 +1,92 @@
-# @seamless-auth/server-express
+# @seamless-auth/express
 
-### Seamless Auth Express Adapter
+[![npm version](https://img.shields.io/npm/v/@seamless-auth/express.svg)](https://www.npmjs.com/package/@seamless-auth/express)
+[![test coverage](https://img.shields.io/badge/coverage-coming%20soon-lightgrey)](#testing)
+[![license](https://img.shields.io/badge/license-AGPL--3.0-blue)](#license)
 
-A secure, passwordless **server-side adapter** that connects your Express API to a private Seamless Auth Server.
+### Seamless Auth – Express Adapter
 
-It proxies all authentication flows, manages signed cookies, and gives you out-of-the-box middleware for verifying users and enforcing roles.
+A secure, passwordless **server-side adapter** for Express that connects your API to a private **Seamless Auth Server**.
+
+This package:
+
+- Proxies authentication flows
+- Manages signed, HttpOnly session cookies
+- Enforces authentication and authorization in your API
+- Handles all API ↔ Auth Server communication via short-lived service tokens
 
 > **npm:** https://www.npmjs.com/package/@seamless-auth/express  
 > **Docs:** https://docs.seamlessauth.com  
 > **Repo:** https://github.com/fells-code/seamless-auth-server
 
-> Couple with https://github.com/fells-code/seamless-auth/react for an end to end seamless experience
-
-> Or get a full starter application with https://github.com/fells-code/create-seamless
+Pair this with:
 
----
+- **React SDK:** https://github.com/fells-code/seamless-auth-react
+- **Starter app:** https://github.com/fells-code/create-seamless
 
 ---
 
 ## Installation
 
 ```bash
-npm install @seamless-auth/server-express
+npm install @seamless-auth/express
 # or
-yarn add @seamless-auth/server-express
+yarn add @seamless-auth/express
 ```
 
-## Quick Example
+---
+
+## Quick Start
 
 ```ts
 import express from "express";
 import cookieParser from "cookie-parser";
-import createSeamlessAuthServer, {
+import {
+  createSeamlessAuthServer,
   requireAuth,
   requireRole,
-} from "@seamless-auth/server-express";
+} from "@seamless-auth/express";
 
 const app = express();
+app.use(express.json());
 app.use(cookieParser());
 
-// Public Seamless Auth endpoints
+// Mount Seamless Auth routes
 app.use(
   "/auth",
-  createSeamlessAuthServer({ authServerUrl: process.env.AUTH_SERVER_URL! })
+  createSeamlessAuthServer({
+    authServerUrl: process.env.AUTH_SERVER_URL!,
+  }),
 );
 
-// Everything after this line requires authentication
+// Everything below requires authentication
 app.use(requireAuth());
 
-app.get("/api/me", (req, res) => res.json({ user: (req as any).user }));
-app.get("/admin", requireRole("admin"), (req, res) =>
-  res.json({ message: "Welcome admin!" })
-);
+app.get("/api/me", (req, res) => {
+  res.json({ user: req.user });
+});
+
+app.get("/admin", requireRole("admin"), (req, res) => {
+  res.json({ message: "Welcome admin!" });
+});
 
-app.listen(5000, () => console.log("Portal API running on :5000"));
+app.listen(5000, () => console.log("API running on http://localhost:3000"));
 ```
 
 ---
 
-# Full Documentation
-
 ## Overview
 
-`@seamless-auth/express` lets your backend API act as an authentication and authorization server using Seamless Auth.
+`@seamless-auth/express` lets your backend API act as the **security boundary** for authentication and authorization.
 
-It transparently proxies and validates authentication flows so your frontend can use a single API endpoint for:
+Your API:
 
-- Login / Registration / Logout
-- User introspection (`/auth/me`)
-- Session cookies (signed JWTs)
-- Role & permission guards
-- Internal Auth Server communication (JWKS + service tokens)
+- owns user session cookies
+- verifies identity locally
+- asserts identity upstream using service tokens
+- never forwards browser cookies to the Auth Server
 
-Everything happens securely between your API and a private Seamless Auth Server.
+This keeps trust boundaries clean and auditable.
 
 ---
 
@@ -84,9 +98,9 @@ Everything happens securely between your API and a private Seamless Auth Server.
      ▼
 [Your Express API]
    ├─ createSeamlessAuthServer()  ← mounts /auth routes
-   ├─ requireAuth()               ← verifies signed cookie JWT
-   ├─ requireRole('admin')        ← role-based guard
-   └─ getSeamlessUser()           ← calls Auth Server
+   ├─ requireAuth()               ← verifies access cookie
+   ├─ requireRole("admin")        ← role-based guard
+   └─ getSeamlessUser()           ← optional user hydration
      │
      ▼
 [Private Seamless Auth Server]
@@ -96,12 +110,14 @@ 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        | `Obtained via the auth portal` |
-| `FRONTEND_URL`                | URL of your website or https://localhost:5001 | `https://mySite.com`           |
+| 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`                                             |
 
 ---
 
@@ -109,35 +125,35 @@ Everything happens securely between your API and a private Seamless Auth Server.
 
 ### `createSeamlessAuthServer(options)`
 
-Mounts an Express router exposing the full Seamless Auth flow:
+Mounts an Express router that exposes the full Seamless Auth flow under `/auth`.
+
+Routes include:
 
 - `/auth/login/start`
 - `/auth/login/finish`
-- `/auth/webauthn/...`
-- `/auth/registration/...`
-- `/auth/me`
+- `/auth/webauthn/*`
+- `/auth/registration/*`
+- `/auth/users/me`
 - `/auth/logout`
 
 **Options**
 
 ```ts
 {
-  authServerUrl: string;        // required
-  cookieDomain?: string;
-  cookieNameOverrides?: {
-    preauth?: string;
-    registration?: string;
-    access?: string;
-  };
+  authServerUrl: string;   // required
+  cookieDomain?: string;  // optional (defaults to host)
+  accessCookieName?: string;
+  registrationCookieName?: string;
+  refreshCookieName?: string;
+  preAuthCookieName?: string;
 }
 ```
 
 ---
 
-### `requireAuth(cookieName?: string)`
+### `requireAuth(options?)`
 
-Middleware that validates the signed access cookie (`seamless_auth_access` by default)  
-and attaches the decoded user payload to `req.user`.
+Express middleware that verifies a signed access cookie and attaches the decoded user payload to `req.user`.
 
 ```ts
 app.get("/api/profile", requireAuth(), (req, res) => {
@@ -147,10 +163,11 @@ app.get("/api/profile", requireAuth(), (req, res) => {
 
 ---
 
-### `requireRole(role: string, cookieName?: string)`
+### `requireRole(role: string)`
+
+Role-based authorization middleware.
 
-Role-based authorization guard.  
-Blocks non-matching roles with HTTP 403.
+Blocks requests when the authenticated user does not have the required role.
 
 ```ts
 app.get("/admin", requireRole("admin"), (req, res) => {
@@ -162,108 +179,67 @@ app.get("/admin", requireRole("admin"), (req, res) => {
 
 ### `getSeamlessUser(req, authServerUrl, cookieName?)`
 
-Calls the Auth Server’s `/internal/session/introspect` endpoint using a signed service JWT  
-and returns the Seamless user object.
+Optional helper that calls the Auth Server to retrieve the **fully hydrated user object**.
+
+This does **not** enforce authentication.
 
 ```ts
-const user = await getSeamlessUser(req, process.env.AUTH_SERVER_URL!);
+const user = await getSeamlessUser(req, process.env.AUTH_SERVER_URL);
 ```
 
-User shape
+Returned shape (example):
 
 ```ts
 {
   id: string;
   email: string;
   phone: string;
-  roles: string[]
+  roles: string[];
 }
 ```
 
+---
+
 ## End-to-End Flow
 
 1. **Frontend** → `/auth/login/start`  
-   → API proxies to Seamless Auth Server  
-   → sets short-lived pre-auth cookie.
+   API proxies request and sets a short-lived _pre-auth_ cookie.
 
 2. **Frontend** → `/auth/webauthn/finish`  
-   → API proxies, validates, sets access cookie (`seamless-access`).
+   API verifies response and sets a signed access cookie.
 
-3. **Subsequent API calls** → `/api/...`  
-   → `requireAuth()` verifies cookie and attaches user.  
-   → Role routes use `requireRole()`.
+3. **API routes** → `/api/*`  
+   `requireAuth()` verifies the cookie and attaches `req.user`.
 
 ---
 
 ## Local Development
 
-In order to develop with your Seamless Auth server instance, you will need to have:
-
-- Created an account @ https://dashboard.seamlessauth.com
-- Created a new Seamless Auth application
-
-Example env:
-
 ```bash
-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
+AUTH_SERVER_URL=http://localhost:5312
+SEAMLESS_SERVICE_TOKEN=generated-secret
+COOKIE_SIGNING_KEY=local-dev-key
+FRONTEND_URL=https://localhost:5001
 ```
 
 ---
 
-## Example Middleware Stack
-
-```ts
-const AUTH_SERVER_URL = process.env.AUTH_SERVER_URL!;
-app.use(cors({ origin: "https://localhost:5001", credentials: true }));
-app.use(express.json());
-app.use(cookieParser());
-app.use("/auth", createSeamlessAuthServer({ authServerUrl: AUTH_SERVER_URL }));
-app.use(requireAuth());
-```
-
----
-
-## Security Model
-
-| Layer                 | Auth Mechanism                        | Signed By          |
-| --------------------- | ------------------------------------- | ------------------ |
-| **Frontend ↔ API**    | Signed JWT in HttpOnly cookie (HS256) | Client API         |
-| **API ↔ Auth Server** | Bearer Service JWT (RS256)            | API’s private key  |
-| **Auth Server**       | Validates service tokens via JWKS     | Seamless Auth JWKS |
-
-All tokens and cookies are stateless and cryptographically verifiable.
-
----
-
 ## Testing
 
-You can mock `requireAuth` and test Express routes via `supertest`.
-
-Example:
+This package includes **Express smoke tests** using `supertest`.
 
-```ts
-import { requireAuth } from "@seamless-auth/server-express";
-app.get("/api/test", requireAuth(), (req, res) => res.json({ ok: true }));
-```
+Core authentication logic is tested separately in `@seamless-auth/core`.
 
 ---
 
-## Roadmap
+## License
 
-| Feature                                      | Status      |
-| -------------------------------------------- | ----------- |
-| JWKS-verified response signing               | ✅          |
-| OIDC discovery & SSO readiness               | planned     |
-| Federation (Google / Okta)                   | future      |
-| Multi-framework adapters (Next.js / Fastify) | coming soon |
+**AGPL-3.0-only** © 2026 Fells Code LLC
 
----
+This license ensures:
 
-## License
+- transparency of security-critical code
+- freedom to self-host and modify
+- sustainability of the managed service offering
 
-MIT © 2025 Fells Code LLC  
-Part of the **Seamless Auth** ecosystem.
-https://seamlessauth.com
+See [`LICENSE`](./LICENSE) for details.

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { JwtPayload } from 'jsonwebtoken';
 interface SeamlessAuthServerOptions {
     authServerUrl: string;
     cookieDomain?: string;
-    accesscookieName?: string;
+    accessCookieName?: string;
     registrationCookieName?: string;
     refreshCookieName?: string;
     preAuthCookieName?: string;
@@ -38,7 +38,7 @@ interface SeamlessAuthServerOptions {
  * app.use("/auth", createSeamlessAuthServer({
  *   authServerUrl: "https://identifier.seamlessauth.com",
  *   cookieDomain: "mycompany.com",
- *   accesscookieName: "sa_access",
+ *   accessCookieName: "sa_access",
  *   registrationCookieName: "sa_registration",
  *   refreshCookieName: "sa_refresh",
  * }));
@@ -47,7 +47,7 @@ interface SeamlessAuthServerOptions {
  * @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
+ *   - `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
@@ -106,7 +106,22 @@ declare function createSeamlessAuthServer(opts: SeamlessAuthServerOptions): Rout
  * @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>;
+interface AuthenticatedRequest extends Request {
+    user?: JwtPayload;
+}
+interface RequireAuthOptions {
+    cookieName?: string;
+    cookieSecret: string;
+}
+/**
+ * Express middleware that enforces authentication
+ * using an already-issued Seamless Auth access cookie.
+ *
+ * NOTE:
+ * - 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;
 
 /**
  * Express middleware that enforces role-based authorization for Seamless Auth sessions.
@@ -156,58 +171,23 @@ declare function requireAuth(cookieName?: string, refreshCookieName?: string, co
  */
 declare function requireRole(role: string, cookieName?: string): RequestHandler;
 
-interface CookieRequest extends Request {
-    cookiePayload?: JwtPayload;
+interface EnsureCookiesMiddlewareOptions {
+    authServerUrl: string;
+    cookieDomain?: string;
+    accessCookieName: string;
+    registrationCookieName: string;
+    refreshCookieName: string;
+    preAuthCookieName: string;
+    cookieSecret: string;
+    serviceSecret: string;
+    issuer: string;
+    audience: string;
+    keyId: string;
 }
+declare function createEnsureCookiesMiddleware(opts: EnsureCookiesMiddlewareOptions): (req: Request & {
+    cookiePayload?: any;
+}, res: Response, next: NextFunction) => Promise<void>;
 
-/**
- * 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>;
+declare function getSeamlessUser<T = any>(req: Request, authServerUrl: string, cookieName?: string): Promise<T | null>;
 
-export { type SeamlessAuthServerOptions, createSeamlessAuthServer as default, getSeamlessUser, requireAuth, requireRole };
+export { type SeamlessAuthServerOptions, createEnsureCookiesMiddleware, createSeamlessAuthServer as default, getSeamlessUser, requireAuth, requireRole };