@seamless-auth/express 0.2.0 → 0.3.1

package/README.md

@@ -14,6 +14,7 @@ This package:
 - Manages signed, HttpOnly session cookies
 - Enforces authentication and authorization in your API
 - Handles all API ↔ Auth Server communication via short-lived service tokens
+- Establishes the initializer surface for adopter-supplied auth messaging
 
 > **npm:** https://www.npmjs.com/package/@seamless-auth/express  
 > **Docs:** https://docs.seamlessauth.com  
@@ -149,9 +150,26 @@ Routes include:
   registrationCookieName?: string;
   refreshCookieName?: string;
   preAuthCookieName?: string;
+  messaging?: {
+    email?: EmailTransport;
+    sms?: SmsTransport;
+    handlers?: Partial<AuthMessagingHandlers>;
+    overrides?: AuthMessageOverrides;
+  };
 }
 ```
 
+`messaging` is the initializer-facing contract for adopter-supplied auth messaging capabilities.
+
+When `messaging` is provided, `@seamless-auth/express` requests external-delivery payloads from the upstream auth server for auth-message flows and completes delivery locally through the configured transports or handlers.
+
+This currently applies to:
+
+- OTP email
+- OTP SMS
+- magic-link email
+- bootstrap invite email
+
 ---
 
 ### `requireAuth(options?)`

package/dist/createServer.d.ts

@@ -0,0 +1,78 @@
+import { Router } from "express";
+import type { SeamlessAuthMessagingOptions } from "./messaging";
+export type SeamlessAuthServerOptions = {
+    authServerUrl: string;
+    cookieSecret: string;
+    serviceSecret: string;
+    issuer: string;
+    audience: string;
+    jwksKid?: string;
+    cookieDomain?: string;
+    accessCookieName?: string;
+    registrationCookieName?: string;
+    refreshCookieName?: string;
+    preAuthCookieName?: string;
+    messaging?: SeamlessAuthMessagingOptions;
+};
+export 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.
+ *
+ * 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",
+ *   cookieSecret: "someLongRandomValue"
+ *   serviceSecret: "someLongRandomValueToo"
+ *   jwksKid: "dev-main"
+ *   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)
+ *   - `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
+ *   - `refreshCookieName` — Name of the refresh token cookie
+ *   - `preAuthCookieName` — Name of the cookie used during login initiation
+ *   - `messaging` — Optional auth-messaging transports, handlers, and overrides
+ *
+ * @returns An Express `Router` preconfigured with all Seamless Auth routes.
+ */
+export declare function createSeamlessAuthServer(opts: SeamlessAuthServerOptions): Router;
+//# sourceMappingURL=createServer.d.ts.map

package/dist/createServer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createServer.d.ts","sourceRoot":"","sources":["../src/createServer.ts"],"names":[],"mappings":"AAAA,OAAgB,EAAqB,MAAM,EAAE,MAAM,SAAS,CAAC;AAI7D,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,aAAa,CAAC;AAqDhE,MAAM,MAAM,yBAAyB,GAAG;IACtC,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,SAAS,CAAC,EAAE,4BAA4B,CAAC;CAC1C,CAAC;AAEF,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,yBAAyB,GAC9B,MAAM,CAkPR"}

package/dist/getSeamlessUser.d.ts

@@ -0,0 +1,4 @@
+import type { Request } from "express";
+import { SeamlessAuthServerOptions } from "./createServer";
+export declare function getSeamlessUser(req: Request, opts: SeamlessAuthServerOptions): Promise<any>;
+//# sourceMappingURL=getSeamlessUser.d.ts.map

package/dist/getSeamlessUser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getSeamlessUser.d.ts","sourceRoot":"","sources":["../src/getSeamlessUser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAMvC,OAAO,EAAE,yBAAyB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,wBAAsB,eAAe,CACnC,GAAG,EAAE,OAAO,EACZ,IAAI,EAAE,yBAAyB,gBAUhC"}

package/dist/handlers/admin.d.ts

@@ -0,0 +1,14 @@
+import { Request, Response } from "express";
+import { SeamlessAuthServerOptions } from "../createServer";
+export declare const getUsers: (req: Request, res: Response, opts: SeamlessAuthServerOptions) => Promise<Response<any, Record<string, any>>>;
+export declare const createUser: (req: Request, res: Response, opts: SeamlessAuthServerOptions) => Promise<Response<any, Record<string, any>>>;
+export declare const deleteUser: (req: Request, res: Response, opts: SeamlessAuthServerOptions) => Promise<Response<any, Record<string, any>>>;
+export declare const updateUser: (req: Request, res: Response, opts: SeamlessAuthServerOptions) => Promise<Response<any, Record<string, any>>>;
+export declare const getUserDetail: (req: Request, res: Response, opts: SeamlessAuthServerOptions) => Promise<Response<any, Record<string, any>>>;
+export declare const getUserAnomalies: (req: Request, res: Response, opts: SeamlessAuthServerOptions) => Promise<Response<any, Record<string, any>>>;
+export declare const getAuthEvents: (req: Request, res: Response, opts: SeamlessAuthServerOptions) => Promise<Response<any, Record<string, any>>>;
+export declare const getCredentialCount: (req: Request, res: Response, opts: SeamlessAuthServerOptions) => Promise<Response<any, Record<string, any>>>;
+export declare const listAllSessions: (req: Request, res: Response, opts: SeamlessAuthServerOptions) => Promise<Response<any, Record<string, any>>>;
+export declare const listUserSessions: (req: Request, res: Response, opts: SeamlessAuthServerOptions) => Promise<Response<any, Record<string, any>>>;
+export declare const revokeAllUserSessions: (req: Request, res: Response, opts: SeamlessAuthServerOptions) => Promise<Response<any, Record<string, any>>>;
+//# sourceMappingURL=admin.d.ts.map

package/dist/handlers/admin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../../src/handlers/admin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAgB5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAS5D,eAAO,MAAM,QAAQ,GACnB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,MAAM,yBAAyB,gDAQ9B,CAAC;AAEJ,eAAO,MAAM,UAAU,GACrB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,MAAM,yBAAyB,gDAS9B,CAAC;AAEJ,eAAO,MAAM,UAAU,GACrB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,MAAM,yBAAyB,gDAQ9B,CAAC;AAEJ,eAAO,MAAM,UAAU,GACrB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,MAAM,yBAAyB,gDAS9B,CAAC;AAEJ,eAAO,MAAM,aAAa,GACxB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,MAAM,yBAAyB,gDAQ9B,CAAC;AAEJ,eAAO,MAAM,gBAAgB,GAC3B,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,MAAM,yBAAyB,gDAQ9B,CAAC;AAEJ,eAAO,MAAM,aAAa,GACxB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,MAAM,yBAAyB,gDAS9B,CAAC;AAEJ,eAAO,MAAM,kBAAkB,GAC7B,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,MAAM,yBAAyB,gDAQ9B,CAAC;AAEJ,eAAO,MAAM,eAAe,GAC1B,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,MAAM,yBAAyB,gDAS9B,CAAC;AAEJ,eAAO,MAAM,gBAAgB,GAC3B,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,MAAM,yBAAyB,gDAQ9B,CAAC;AAEJ,eAAO,MAAM,qBAAqB,GAChC,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,MAAM,yBAAyB,gDAQ9B,CAAC"}

package/dist/handlers/bootstrapAdmininvite.d.ts

@@ -0,0 +1,4 @@
+import { Request, Response } from "express";
+import { SeamlessAuthServerOptions } from "../createServer";
+export declare function bootstrapAdminInvite(req: Request, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>> | undefined>;
+//# sourceMappingURL=bootstrapAdmininvite.d.ts.map

package/dist/handlers/bootstrapAdmininvite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrapAdmininvite.d.ts","sourceRoot":"","sources":["../../src/handlers/bootstrapAdmininvite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAG5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,2DAsBhC"}

package/dist/handlers/finishLogin.d.ts

@@ -0,0 +1,6 @@
+import { Request, Response } from "express";
+import { SeamlessAuthServerOptions } from "../createServer";
+export declare function finishLogin(req: Request & {
+    cookiePayload?: any;
+}, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>> | undefined>;
+//# sourceMappingURL=finishLogin.d.ts.map

package/dist/handlers/finishLogin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finishLogin.d.ts","sourceRoot":"","sources":["../../src/handlers/finishLogin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAI5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,wBAAsB,WAAW,CAC/B,GAAG,EAAE,OAAO,GAAG;IAAE,aAAa,CAAC,EAAE,GAAG,CAAA;CAAE,EACtC,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,2DA+ChC"}

package/dist/handlers/finishRegister.d.ts

@@ -0,0 +1,6 @@
+import { Request, Response } from "express";
+import { SeamlessAuthServerOptions } from "../createServer";
+export declare function finishRegister(req: Request & {
+    cookiePayload?: any;
+}, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>> | undefined>;
+//# sourceMappingURL=finishRegister.d.ts.map

package/dist/handlers/finishRegister.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finishRegister.d.ts","sourceRoot":"","sources":["../../src/handlers/finishRegister.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAI5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAG5D,wBAAsB,cAAc,CAClC,GAAG,EAAE,OAAO,GAAG;IAAE,aAAa,CAAC,EAAE,GAAG,CAAA;CAAE,EACtC,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,2DAkEhC"}

package/dist/handlers/internalMetrics.d.ts

@@ -0,0 +1,9 @@
+import { Request, Response } from "express";
+import { SeamlessAuthServerOptions } from "../createServer";
+export declare function getAuthEventSummary(req: Request, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>>>;
+export declare function getAuthEventTimeseries(req: Request, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>>>;
+export declare function getLoginStats(req: Request, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>>>;
+export declare function getSecurityAnomalies(req: Request, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>>>;
+export declare function getDashboardMetrics(req: Request, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>>>;
+export declare function getGroupedEventSummary(req: Request, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>>>;
+//# sourceMappingURL=internalMetrics.d.ts.map

package/dist/handlers/internalMetrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internalMetrics.d.ts","sourceRoot":"","sources":["../../src/handlers/internalMetrics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAW5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAS5D,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,+CAWhC;AAED,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,+CAWhC;AAED,wBAAsB,aAAa,CACjC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,+CAUhC;AAED,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,+CAUhC;AAED,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,+CAUhC;AAED,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,+CAUhC"}

package/dist/handlers/login.d.ts

@@ -0,0 +1,4 @@
+import { Request, Response } from "express";
+import { SeamlessAuthServerOptions } from "../createServer";
+export declare function login(req: Request, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>> | undefined>;
+//# sourceMappingURL=login.d.ts.map

package/dist/handlers/login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../src/handlers/login.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAG5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,wBAAsB,KAAK,CACzB,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,2DA4ChC"}

package/dist/handlers/logout.d.ts

@@ -0,0 +1,4 @@
+import { Request, Response } from "express";
+import { SeamlessAuthServerOptions } from "../createServer";
+export declare function logout(req: Request, res: Response, opts: SeamlessAuthServerOptions): Promise<void>;
+//# sourceMappingURL=logout.d.ts.map

package/dist/handlers/logout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logout.d.ts","sourceRoot":"","sources":["../../src/handlers/logout.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAG5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,wBAAsB,MAAM,CAC1B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,iBAYhC"}

package/dist/handlers/me.d.ts

@@ -0,0 +1,6 @@
+import { Request, Response } from "express";
+import { SeamlessAuthServerOptions } from "../createServer";
+export declare function me(req: Request & {
+    cookiePayload?: any;
+}, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>> | undefined>;
+//# sourceMappingURL=me.d.ts.map

package/dist/handlers/me.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"me.d.ts","sourceRoot":"","sources":["../../src/handlers/me.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAI5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,wBAAsB,EAAE,CACtB,GAAG,EAAE,OAAO,GAAG;IAAE,aAAa,CAAC,EAAE,GAAG,CAAA;CAAE,EACtC,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,2DAoBhC"}

package/dist/handlers/pollMagicLinkConfirmation.d.ts

@@ -0,0 +1,6 @@
+import { Request, Response } from "express";
+import { SeamlessAuthServerOptions } from "../createServer";
+export declare function pollMagicLinkConfirmation(req: Request & {
+    cookiePayload?: any;
+}, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>> | undefined>;
+//# sourceMappingURL=pollMagicLinkConfirmation.d.ts.map

package/dist/handlers/pollMagicLinkConfirmation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pollMagicLinkConfirmation.d.ts","sourceRoot":"","sources":["../../src/handlers/pollMagicLinkConfirmation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAI5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,OAAO,GAAG;IAAE,aAAa,CAAC,EAAE,GAAG,CAAA;CAAE,EACtC,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,2DAgDhC"}

package/dist/handlers/register.d.ts

@@ -0,0 +1,4 @@
+import { Request, Response } from "express";
+import { SeamlessAuthServerOptions } from "../createServer";
+export declare function register(req: Request, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>> | undefined>;
+//# sourceMappingURL=register.d.ts.map

package/dist/handlers/register.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/handlers/register.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAI5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,wBAAsB,QAAQ,CAC5B,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,2DAqDhC"}

package/dist/handlers/requestMagicLink.d.ts

@@ -0,0 +1,7 @@
+import { Request, Response } from "express";
+import { SeamlessAuthServerOptions } from "../createServer";
+export declare function requestMagicLink(req: Request & {
+    cookiePayload?: any;
+    user?: any;
+}, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>>>;
+//# sourceMappingURL=requestMagicLink.d.ts.map

package/dist/handlers/requestMagicLink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestMagicLink.d.ts","sourceRoot":"","sources":["../../src/handlers/requestMagicLink.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAI5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,wBAAsB,gBAAgB,CACpC,GAAG,EAAE,OAAO,GAAG;IAAE,aAAa,CAAC,EAAE,GAAG,CAAC;IAAC,IAAI,CAAC,EAAE,GAAG,CAAA;CAAE,EAClD,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,+CAyBhC"}

package/dist/handlers/requestOtp.d.ts

@@ -0,0 +1,7 @@
+import { Request, Response } from "express";
+import { SeamlessAuthServerOptions } from "../createServer";
+export declare function requestOtp(req: Request & {
+    cookiePayload?: any;
+    user?: any;
+}, res: Response, opts: SeamlessAuthServerOptions, kind: "email" | "phone"): Promise<Response<any, Record<string, any>>>;
+//# sourceMappingURL=requestOtp.d.ts.map

package/dist/handlers/requestOtp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requestOtp.d.ts","sourceRoot":"","sources":["../../src/handlers/requestOtp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAI5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,wBAAsB,UAAU,CAC9B,GAAG,EAAE,OAAO,GAAG;IAAE,aAAa,CAAC,EAAE,GAAG,CAAC;IAAC,IAAI,CAAC,EAAE,GAAG,CAAA;CAAE,EAClD,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,EAC/B,IAAI,EAAE,OAAO,GAAG,OAAO,+CA0BxB"}

package/dist/handlers/sessions.d.ts

@@ -0,0 +1,6 @@
+import { Request, Response } from "express";
+import { SeamlessAuthServerOptions } from "../createServer";
+export declare function listSessions(req: Request, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>>>;
+export declare function revokeSession(req: Request, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>>>;
+export declare function revokeAllSessions(req: Request, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>>>;
+//# sourceMappingURL=sessions.d.ts.map

package/dist/handlers/sessions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sessions.d.ts","sourceRoot":"","sources":["../../src/handlers/sessions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAQ5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAS5D,wBAAsB,YAAY,CAChC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,+CAUhC;AAED,wBAAsB,aAAa,CACjC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,+CAUhC;AAED,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,+CAUhC"}

package/dist/handlers/systemConfig.d.ts

@@ -0,0 +1,6 @@
+import { Request, Response } from "express";
+import { SeamlessAuthServerOptions } from "../createServer";
+export declare function getAvailableRoles(req: Request, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>> | undefined>;
+export declare function getSystemConfigAdmin(req: Request, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>> | undefined>;
+export declare function updateSystemConfig(req: Request, res: Response, opts: SeamlessAuthServerOptions): Promise<Response<any, Record<string, any>> | undefined>;
+//# sourceMappingURL=systemConfig.d.ts.map

package/dist/handlers/systemConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"systemConfig.d.ts","sourceRoot":"","sources":["../../src/handlers/systemConfig.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAQ5C,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,2DAchC;AAED,wBAAsB,oBAAoB,CACxC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,2DAchC;AAED,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,yBAAyB,2DAehC"}

package/dist/index.d.ts

@@ -1,197 +1,9 @@
-import { Router, Request, Response, NextFunction, RequestHandler } from 'express';
-
-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.
- *
- * 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",
- *   cookieSecret: "someLongRandomValue"
- *   serviceSecret: "someLongRandomValueToo"
- *   jwksKid: "dev-main"
- *   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)
- *   - `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
- *   - `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;
-
-interface RequireAuthOptions {
-    cookieName?: string;
-    cookieSecret: string;
-}
-/**
- * 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.
- */
-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: Request, res: Response, next: NextFunction) => void;
-
-/**
- * Express middleware that enforces role-based authorization for Seamless Auth.
- *
- * This middleware assumes `requireAuth()` has already:
- * - authenticated the request
- * - populated `req.user` with the authenticated session payload
- *
- * `requireRole` performs **authorization only**. It does not inspect cookies,
- * verify tokens, or read environment variables.
- *
- * If any of the required roles are present on the user, access is granted.
- * Otherwise, a 403 Forbidden response is returned.
- *
- *  * ### 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 requiredRoles - A role or list of roles required to access the route
- */
-declare function requireRole(requiredRoles: string | string[]): RequestHandler;
-
-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, res: Response, next: NextFunction) => Promise<void>;
-
-declare function getSeamlessUser(req: Request, opts: SeamlessAuthServerOptions): Promise<any>;
-
-export { type SeamlessAuthServerOptions, type SeamlessAuthUser, createEnsureCookiesMiddleware, createSeamlessAuthServer as default, getSeamlessUser, requireAuth, requireRole };
+import { createSeamlessAuthServer, SeamlessAuthServerOptions, SeamlessAuthUser } from "./createServer";
+export { SeamlessAuthServerOptions, SeamlessAuthUser };
+export type { AuthMessageOverrides, AuthMessagingHandlers, DeliveryResult, EmailMessage, EmailTransport, SeamlessAuthMessagingOptions, SmsMessage, SmsTransport, } from "./messaging";
+export { requireAuth } from "./middleware/requireAuth";
+export { requireRole } from "./middleware/requireRole";
+export { createEnsureCookiesMiddleware } from "./middleware/ensureCookies";
+export { getSeamlessUser } from "./getSeamlessUser";
+export default createSeamlessAuthServer;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,gBAAgB,EACjB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,yBAAyB,EAAE,gBAAgB,EAAE,CAAC;AACvD,YAAY,EACV,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,YAAY,EACZ,cAAc,EACd,4BAA4B,EAC5B,UAAU,EACV,YAAY,GACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AACvD,OAAO,EAAE,6BAA6B,EAAE,MAAM,4BAA4B,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,eAAe,wBAAwB,CAAC"}

package/dist/index.js

@@ -139,11 +139,12 @@ import { finishLoginHandler } from "@seamless-auth/core/handlers/finishLogin";
 // src/internal/buildAuthorization.ts
 import { createServiceToken } from "@seamless-auth/core";
 function buildServiceAuthorization(req, opts) {
-  if (!req.cookiePayload?.sub && !req.user.sub) {
+  const subject = req.cookiePayload?.sub || req.user?.sub;
+  if (!subject) {
     return void 0;
   }
   const token = createServiceToken({
-    subject: req.cookiePayload?.sub || req.user.sub,
+    subject,
     issuer: opts.issuer,
     audience: opts.audience,
     serviceSecret: opts.serviceSecret,
@@ -194,6 +195,174 @@ async function finishLogin(req, res, opts) {
 
 // src/handlers/register.ts
 import { registerHandler } from "@seamless-auth/core/handlers/register";
+
+// src/internal/deliverAuthMessage.ts
+function applyEmailOverride(override, input, defaults, appName) {
+  return override ? override(input, defaults, { appName }) : defaults;
+}
+function applySmsOverride(override, input, defaults, appName) {
+  return override ? override(input, defaults, { appName }) : defaults;
+}
+function buildOtpEmailMessage(input, messaging) {
+  const appName = messaging.defaults?.appName ?? "Seamless Auth";
+  return applyEmailOverride(
+    messaging.overrides?.otpEmail,
+    {
+      to: input.to,
+      token: input.token,
+      from: messaging.defaults?.emailFrom,
+      subject: `${appName} - Verify your email`
+    },
+    {
+      to: input.to,
+      from: messaging.defaults?.emailFrom,
+      subject: `${appName} - Verify your email`,
+      text: `Verify your account with ${appName}.
+
+Your verification code is: ${input.token}
+
+If you did not request this code, you can safely ignore this message.`,
+      html: `<div><h1>Verify your account with ${appName}</h1><p>Please use the verification code below:</p><p><strong>${input.token}</strong></p><p>If you did not request this code, you can safely ignore this message.</p></div>`
+    },
+    appName
+  );
+}
+function buildOtpSmsMessage(input, messaging) {
+  const appName = messaging.defaults?.appName ?? "Seamless Auth";
+  return applySmsOverride(
+    messaging.overrides?.otpSms,
+    {
+      to: input.to,
+      token: input.token,
+      from: messaging.defaults?.smsFrom
+    },
+    {
+      to: input.to,
+      from: messaging.defaults?.smsFrom,
+      body: `Your ${appName} verification code is: ${input.token}. No one will ever ask you for this code. Do not share it.`
+    },
+    appName
+  );
+}
+function buildMagicLinkMessage(input, messaging) {
+  const appName = messaging.defaults?.appName ?? "Seamless Auth";
+  return applyEmailOverride(
+    messaging.overrides?.magicLinkEmail,
+    {
+      to: input.to,
+      magicLinkUrl: input.magicLinkUrl,
+      token: input.token,
+      from: messaging.defaults?.emailFrom,
+      subject: `${appName} - Your sign-in link`
+    },
+    {
+      to: input.to,
+      from: messaging.defaults?.emailFrom,
+      subject: `${appName} - Your sign-in link`,
+      text: `Use the link below to sign in to ${appName}:
+
+${input.magicLinkUrl}
+
+If you did not request this email, you can safely ignore it.`,
+      html: `<div><h1>Sign in to ${appName}</h1><p>Use the link below to complete sign-in:</p><p><a href="${input.magicLinkUrl}">${input.magicLinkUrl}</a></p><p>If you did not request this email, you can safely ignore it.</p></div>`
+    },
+    appName
+  );
+}
+function buildBootstrapInviteMessage(input, messaging) {
+  const appName = messaging.defaults?.appName ?? "Seamless Auth";
+  return applyEmailOverride(
+    messaging.overrides?.bootstrapInviteEmail,
+    {
+      to: input.to,
+      inviteUrl: input.inviteUrl,
+      token: input.token,
+      from: messaging.defaults?.emailFrom,
+      subject: `${appName} - Bootstrap invite`
+    },
+    {
+      to: input.to,
+      from: messaging.defaults?.emailFrom,
+      subject: `${appName} - Bootstrap invite`,
+      text: `You have been invited to bootstrap ${appName}.
+
+Use the link below to continue:
+${input.inviteUrl}`,
+      html: `<div><h1>Bootstrap invite for ${appName}</h1><p>Use the link below to continue:</p><p><a href="${input.inviteUrl}">${input.inviteUrl}</a></p></div>`
+    },
+    appName
+  );
+}
+async function deliverAuthMessage(messaging, delivery) {
+  if (!messaging || !delivery) {
+    return;
+  }
+  switch (delivery.kind) {
+    case "otp_email":
+      if (messaging.handlers?.sendOtpEmail) {
+        await messaging.handlers.sendOtpEmail({
+          to: delivery.to,
+          token: delivery.token,
+          from: messaging.defaults?.emailFrom
+        });
+        return;
+      }
+      if (!messaging.email) {
+        throw new Error("Missing email transport for OTP email delivery.");
+      }
+      await messaging.email.send(buildOtpEmailMessage(delivery, messaging));
+      return;
+    case "otp_sms":
+      if (messaging.handlers?.sendOtpSms) {
+        await messaging.handlers.sendOtpSms({
+          to: delivery.to,
+          token: delivery.token,
+          from: messaging.defaults?.smsFrom
+        });
+        return;
+      }
+      if (!messaging.sms) {
+        throw new Error("Missing SMS transport for OTP SMS delivery.");
+      }
+      await messaging.sms.send(buildOtpSmsMessage(delivery, messaging));
+      return;
+    case "magic_link_email":
+      if (messaging.handlers?.sendMagicLinkEmail) {
+        await messaging.handlers.sendMagicLinkEmail({
+          to: delivery.to,
+          token: delivery.token,
+          magicLinkUrl: delivery.magicLinkUrl,
+          from: messaging.defaults?.emailFrom
+        });
+        return;
+      }
+      if (!messaging.email) {
+        throw new Error("Missing email transport for magic link delivery.");
+      }
+      await messaging.email.send(buildMagicLinkMessage(delivery, messaging));
+      return;
+    case "bootstrap_invite_email":
+      if (messaging.handlers?.sendBootstrapInviteEmail) {
+        await messaging.handlers.sendBootstrapInviteEmail({
+          to: delivery.to,
+          inviteUrl: delivery.inviteUrl,
+          from: messaging.defaults?.emailFrom
+        });
+        return;
+      }
+      if (!messaging.email) {
+        throw new Error("Missing email transport for bootstrap invite delivery.");
+      }
+      await messaging.email.send(buildBootstrapInviteMessage(delivery, messaging));
+      return;
+  }
+}
+function stripDelivery(body) {
+  const { delivery: _delivery, ...rest } = body;
+  return rest;
+}
+
+// src/handlers/register.ts
 async function register(req, res, opts) {
   const cookieSigner = {
     secret: opts.cookieSecret,
@@ -205,7 +374,8 @@ async function register(req, res, opts) {
     {
       authServerUrl: opts.authServerUrl,
       cookieDomain: opts.cookieDomain,
-      registrationCookieName: opts.registrationCookieName
+      registrationCookieName: opts.registrationCookieName,
+      externalDelivery: Boolean(opts.messaging)
     }
   );
   if (!cookieSigner.secret) {
@@ -228,9 +398,42 @@ async function register(req, res, opts) {
   if (result.error) {
     return res.status(result.status).json(result.error);
   }
+  if (result.body && typeof result.body === "object" && "delivery" in result.body) {
+    await deliverAuthMessage(
+      opts.messaging,
+      result.body.delivery
+    );
+    return res.status(result.status).json(stripDelivery(result.body)).end();
+  }
   res.status(result.status).json(result.body).end();
 }
 
+// src/handlers/requestOtp.ts
+import { requestOtpHandler } from "@seamless-auth/core/handlers/requestOtpHandler";
+async function requestOtp(req, res, opts, kind) {
+  const result = await requestOtpHandler(
+    {
+      kind,
+      authorization: buildServiceAuthorization(req, opts)
+    },
+    {
+      authServerUrl: opts.authServerUrl,
+      externalDelivery: Boolean(opts.messaging)
+    }
+  );
+  if (result.error) {
+    return res.status(result.status).json(result.error);
+  }
+  if (result.body && typeof result.body === "object" && "delivery" in result.body) {
+    await deliverAuthMessage(
+      opts.messaging,
+      result.body.delivery
+    );
+    return res.status(result.status).json(stripDelivery(result.body));
+  }
+  return res.status(result.status).json(result.body);
+}
+
 // src/handlers/finishRegister.ts
 import { finishRegisterHandler } from "@seamless-auth/core/handlers/finishRegister";
 import { verifyCookieJwt } from "@seamless-auth/core";
@@ -363,6 +566,31 @@ async function pollMagicLinkConfirmation(req, res, opts) {
   res.status(result.status).json(result.body).end();
 }
 
+// src/handlers/requestMagicLink.ts
+import { requestMagicLinkHandler } from "@seamless-auth/core/handlers/requestMagicLinkHandler";
+async function requestMagicLink(req, res, opts) {
+  const result = await requestMagicLinkHandler(
+    {
+      authorization: buildServiceAuthorization(req, opts)
+    },
+    {
+      authServerUrl: opts.authServerUrl,
+      externalDelivery: Boolean(opts.messaging)
+    }
+  );
+  if (result.error) {
+    return res.status(result.status).json(result.error);
+  }
+  if (result.body && typeof result.body === "object" && "delivery" in result.body) {
+    await deliverAuthMessage(
+      opts.messaging,
+      result.body.delivery
+    );
+    return res.status(result.status).json(stripDelivery(result.body));
+  }
+  return res.status(result.status).json(result.body);
+}
+
 // src/handlers/admin.ts
 import {
   getUsersHandler,
@@ -476,11 +704,19 @@ async function bootstrapAdminInvite(req, res, opts) {
   const result = await bootstrapAdminInviteHandler({
     authServerUrl: opts.authServerUrl,
     email: req.body.email,
-    authorization: req.headers["authorization"]
+    authorization: req.headers["authorization"],
+    externalDelivery: Boolean(opts.messaging)
   });
   if (result.error) {
     return res.status(result.status).json({ error: result.error });
   }
+  if (result.body && typeof result.body === "object" && "delivery" in result.body) {
+    await deliverAuthMessage(
+      opts.messaging,
+      result.body.delivery
+    );
+    return res.status(result.status).json(stripDelivery(result.body));
+  }
   res.status(result.status).json(result.body);
 }
 
@@ -644,7 +880,8 @@ function createSeamlessAuthServer(opts) {
     accessCookieName: opts.accessCookieName ?? "seamless-access",
     registrationCookieName: opts.registrationCookieName ?? "seamless-ephemeral",
     refreshCookieName: opts.refreshCookieName ?? "seamless-refresh",
-    preAuthCookieName: opts.preAuthCookieName ?? "seamless-ephemeral"
+    preAuthCookieName: opts.preAuthCookieName ?? "seamless-ephemeral",
+    messaging: opts.messaging
   };
   const proxyWithIdentity = (path, identity, method = "POST") => async (req, res) => {
     if (!req.cookiePayload?.sub) {
@@ -717,11 +954,11 @@ function createSeamlessAuthServer(opts) {
   );
   r.get(
     "/otp/generate-phone-otp",
-    proxyWithIdentity("otp/generate-phone-otp", "preAuth", "GET")
+    (req, res) => requestOtp(req, res, resolvedOpts, "phone")
   );
   r.get(
     "/otp/generate-email-otp",
-    proxyWithIdentity("otp/generate-email-otp", "preAuth", "GET")
+    (req, res) => requestOtp(req, res, resolvedOpts, "email")
   );
   r.post("/login", (req, res) => login(req, res, resolvedOpts));
   r.post(
@@ -739,7 +976,10 @@ function createSeamlessAuthServer(opts) {
     "/users/credentials",
     proxyWithIdentity("users/credentials", "access")
   );
-  r.get("/magic-link", proxyWithIdentity("magic-link", "preAuth", "GET"));
+  r.get(
+    "/magic-link",
+    (req, res) => requestMagicLink(req, res, resolvedOpts)
+  );
   r.get("/magic-link/verify/:token", async (req, res) => {
     const upstream = await authFetch(
       `${resolvedOpts.authServerUrl}/magic-link/verify/${req.params.token}`,

package/dist/internal/buildAuthorization.d.ts

@@ -0,0 +1,6 @@
+import { Request } from "express";
+import { SeamlessAuthServerOptions } from "../createServer";
+export declare function buildServiceAuthorization(req: Request & {
+    cookiePayload?: any;
+}, opts: SeamlessAuthServerOptions): string | undefined;
+//# sourceMappingURL=buildAuthorization.d.ts.map

package/dist/internal/buildAuthorization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildAuthorization.d.ts","sourceRoot":"","sources":["../../src/internal/buildAuthorization.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AAE5D,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,OAAO,GAAG;IAAE,aAAa,CAAC,EAAE,GAAG,CAAA;CAAE,EACtC,IAAI,EAAE,yBAAyB,sBAiBhC"}

package/dist/internal/cookie.d.ts

@@ -0,0 +1,17 @@
+import { JwtPayload } from "jsonwebtoken";
+import { Response } from "express";
+export interface CookieSignerOptions {
+    secret: string;
+    secure: boolean;
+    sameSite: "lax" | "none";
+}
+export interface SetCookieOptions {
+    name: string;
+    payload: JwtPayload;
+    domain?: string;
+    ttlSeconds: number;
+}
+export declare function setSessionCookie(res: Response, opts: SetCookieOptions, signer: CookieSignerOptions): void;
+export declare function clearSessionCookie(res: Response, domain: string | undefined, name: string): void;
+export declare function clearAllCookies(res: Response, domain: string | undefined, ...cookieNames: string[]): void;
+//# sourceMappingURL=cookie.d.ts.map

package/dist/internal/cookie.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cookie.d.ts","sourceRoot":"","sources":["../../src/internal/cookie.ts"],"names":[],"mappings":"AAAA,OAAY,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEnC,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,KAAK,GAAG,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,UAAU,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,QAAQ,EACb,IAAI,EAAE,gBAAgB,EACtB,MAAM,EAAE,mBAAmB,QAe5B;AAED,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,QAAQ,EACb,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,IAAI,EAAE,MAAM,QAGb;AAED,wBAAgB,eAAe,CAC7B,GAAG,EAAE,QAAQ,EACb,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,GAAG,WAAW,EAAE,MAAM,EAAE,QAKzB"}

package/dist/internal/deliverAuthMessage.d.ts

@@ -0,0 +1,6 @@
+import { AuthDeliveryInstruction, SeamlessAuthMessagingOptions } from "../messaging";
+export declare function deliverAuthMessage(messaging: SeamlessAuthMessagingOptions | undefined, delivery: AuthDeliveryInstruction | undefined): Promise<void>;
+export declare function stripDelivery<T extends {
+    delivery?: unknown;
+}>(body: T): Omit<T, "delivery">;
+//# sourceMappingURL=deliverAuthMessage.d.ts.map

package/dist/internal/deliverAuthMessage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deliverAuthMessage.d.ts","sourceRoot":"","sources":["../../src/internal/deliverAuthMessage.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,uBAAuB,EAEvB,4BAA4B,EAE7B,MAAM,cAAc,CAAC;AA2HtB,wBAAsB,kBAAkB,CACtC,SAAS,EAAE,4BAA4B,GAAG,SAAS,EACnD,QAAQ,EAAE,uBAAuB,GAAG,SAAS,GAC5C,OAAO,CAAC,IAAI,CAAC,CA2Ef;AAED,wBAAgB,aAAa,CAAC,CAAC,SAAS;IAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,EAAE,UAAU,CAAC,CAG5F"}

package/dist/messaging.d.ts

@@ -0,0 +1,98 @@
+export type MessagingChannel = "email" | "sms";
+export interface DeliveryResult {
+    accepted: boolean;
+    provider: string;
+    channel: MessagingChannel;
+    messageId?: string;
+    raw?: unknown;
+}
+export interface EmailMessage {
+    to: string;
+    from?: string;
+    subject: string;
+    text: string;
+    html?: string;
+}
+export interface SmsMessage {
+    to: string;
+    from?: string;
+    body: string;
+}
+export interface EmailTransport {
+    readonly name: string;
+    send(message: EmailMessage): Promise<DeliveryResult>;
+}
+export interface SmsTransport {
+    readonly name: string;
+    send(message: SmsMessage): Promise<DeliveryResult>;
+}
+export interface SendOtpEmailInput {
+    to: string;
+    token: string;
+    from?: string;
+    subject?: string;
+}
+export interface SendOtpSmsInput {
+    to: string;
+    token: string | number;
+    from?: string;
+}
+export interface SendMagicLinkEmailInput {
+    to: string;
+    magicLinkUrl: string;
+    token?: string;
+    from?: string;
+    subject?: string;
+}
+export interface SendBootstrapInviteEmailInput {
+    to: string;
+    inviteUrl: string;
+    from?: string;
+    subject?: string;
+}
+export interface AuthMessageOverrideContext {
+    appName?: string;
+}
+export interface AuthMessageOverrides {
+    otpEmail?: (input: SendOtpEmailInput, defaults: EmailMessage, context: AuthMessageOverrideContext) => EmailMessage;
+    otpSms?: (input: SendOtpSmsInput, defaults: SmsMessage, context: AuthMessageOverrideContext) => SmsMessage;
+    magicLinkEmail?: (input: SendMagicLinkEmailInput, defaults: EmailMessage, context: AuthMessageOverrideContext) => EmailMessage;
+    bootstrapInviteEmail?: (input: SendBootstrapInviteEmailInput, defaults: EmailMessage, context: AuthMessageOverrideContext) => EmailMessage;
+}
+export interface AuthMessagingHandlers {
+    sendOtpEmail(input: SendOtpEmailInput): Promise<DeliveryResult>;
+    sendOtpSms(input: SendOtpSmsInput): Promise<DeliveryResult>;
+    sendMagicLinkEmail(input: SendMagicLinkEmailInput): Promise<DeliveryResult>;
+    sendBootstrapInviteEmail(input: SendBootstrapInviteEmailInput): Promise<DeliveryResult>;
+}
+export interface SeamlessAuthMessagingOptions {
+    email?: EmailTransport;
+    sms?: SmsTransport;
+    handlers?: Partial<AuthMessagingHandlers>;
+    overrides?: AuthMessageOverrides;
+    defaults?: {
+        appName?: string;
+        emailFrom?: string;
+        smsFrom?: string;
+    };
+}
+export type AuthDeliveryInstruction = {
+    kind: "otp_email";
+    to: string;
+    token: string;
+} | {
+    kind: "otp_sms";
+    to: string;
+    token: string | number;
+} | {
+    kind: "magic_link_email";
+    to: string;
+    token?: string;
+    magicLinkUrl: string;
+} | {
+    kind: "bootstrap_invite_email";
+    to: string;
+    token?: string;
+    inviteUrl: string;
+};
+//# sourceMappingURL=messaging.d.ts.map

package/dist/messaging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messaging.d.ts","sourceRoot":"","sources":["../src/messaging.ts"],"names":[],"mappings":"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"}

package/dist/middleware/ensureCookies.d.ts

@@ -0,0 +1,16 @@
+import { Request, Response, NextFunction } from "express";
+export interface EnsureCookiesMiddlewareOptions {
+    authServerUrl: string;
+    cookieDomain?: string;
+    accessCookieName: string;
+    registrationCookieName: string;
+    refreshCookieName: string;
+    preAuthCookieName: string;
+    cookieSecret: string;
+    serviceSecret: string;
+    issuer: string;
+    audience: string;
+    keyId: string;
+}
+export declare function createEnsureCookiesMiddleware(opts: EnsureCookiesMiddlewareOptions): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+//# sourceMappingURL=ensureCookies.d.ts.map

package/dist/middleware/ensureCookies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensureCookies.d.ts","sourceRoot":"","sources":["../../src/middleware/ensureCookies.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAK1D,MAAM,WAAW,8BAA8B;IAC7C,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;IAEtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,sBAAsB,EAAE,MAAM,CAAC;IAC/B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,wBAAgB,6BAA6B,CAC3C,IAAI,EAAE,8BAA8B,IAmBlC,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,MAAM,YAAY,mBA0BrB"}

package/dist/middleware/requireAuth.d.ts

@@ -0,0 +1,69 @@
+import { Request, Response, NextFunction } from "express";
+export interface RequireAuthOptions {
+    cookieName?: string;
+    cookieSecret: string;
+}
+/**
+ * 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.
+ */
+export 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().
+ */
+export declare function requireAuth(opts: RequireAuthOptions): (req: Request, res: Response, next: NextFunction) => void;
+//# sourceMappingURL=requireAuth.d.ts.map

package/dist/middleware/requireAuth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requireAuth.d.ts","sourceRoot":"","sources":["../../src/middleware/requireAuth.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI1D,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AACD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAEH,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,IAOjC,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,UAoCjE"}

package/dist/middleware/requireRole.d.ts

@@ -0,0 +1,36 @@
+import { RequestHandler } from "express";
+/**
+ * Express middleware that enforces role-based authorization for Seamless Auth.
+ *
+ * This middleware assumes `requireAuth()` has already:
+ * - authenticated the request
+ * - populated `req.user` with the authenticated session payload
+ *
+ * `requireRole` performs **authorization only**. It does not inspect cookies,
+ * verify tokens, or read environment variables.
+ *
+ * If any of the required roles are present on the user, access is granted.
+ * Otherwise, a 403 Forbidden response is returned.
+ *
+ *  * ### 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 requiredRoles - A role or list of roles required to access the route
+ */
+export declare function requireRole(requiredRoles: string | string[]): RequestHandler;
+//# sourceMappingURL=requireRole.d.ts.map

package/dist/middleware/requireRole.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requireRole.d.ts","sourceRoot":"","sources":["../../src/middleware/requireRole.ts"],"names":[],"mappings":"AAAA,OAAO,EAAmC,cAAc,EAAE,MAAM,SAAS,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,WAAW,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,cAAc,CAiC5E"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seamless-auth/express",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Express adapter for Seamless Auth passwordless authentication",
   "license": "AGPL-3.0-only",
   "type": "module",
@@ -23,10 +23,12 @@
     "node": ">=18"
   },
   "scripts": {
-    "build": "tsup src/index.ts --format esm --out-dir dist --dts --splitting",
+    "build": "npm run build:js && npm run build:types",
+    "build:js": "tsup src/index.ts --format esm --out-dir dist --splitting",
+    "build:types": "tsc -p tsconfig.build.json",
     "dev": "tsc --watch",
-    "test": "npm run build && NODE_OPTIONS=--experimental-vm-modules jest",
-    "test:watch": "npm run build && NODE_OPTIONS=--experimental-vm-modules jest --watch"
+    "test": "npm --prefix ../core run build && npm run build && NODE_OPTIONS=--experimental-vm-modules jest",
+    "test:watch": "npm --prefix ../core run build && npm run build && NODE_OPTIONS=--experimental-vm-modules jest --watch"
   },
   "repository": {
     "type": "git",
@@ -37,7 +39,7 @@
     "express": ">=4.18.0"
   },
   "dependencies": {
-    "@seamless-auth/core": "^0.3.0",
+    "@seamless-auth/core": "^0.4.1",
     "cookie-parser": "^1.4.6",
     "jsonwebtoken": "^9.0.3"
   },