Auth token contract cleanup

.changeset/soft-chefs-retire.md

@@ -0,0 +1,6 @@
+---
+"@seamless-auth/express": patch
+"@seamless-auth/core": patch
+---
+
+Operational tidy work and extension of the logout functions for future use

packages/core/src/ensureCookies.ts

@@ -32,6 +32,7 @@ export interface EnsureCookiesResult {
   user?: {
     sub: string;
     sessionId?: string;
+    token?: string;
     roles?: string[];
   };
   setCookies?: CookieInstruction[];
@@ -107,6 +108,7 @@ const COOKIE_REQUIREMENTS: Record<
     name: "preAuthCookieName",
     required: true,
   },
+  "/logout/all": { name: "accessCookieName", required: true },
   "/logout": { name: "accessCookieName", required: true },
   "/users/me": { name: "accessCookieName", required: true },
   "/organizations": { name: "accessCookieName", required: true },
@@ -223,6 +225,7 @@ export async function ensureCookies(
         ...(refreshed.sessionId === undefined
           ? {}
           : { sessionId: refreshed.sessionId }),
+        token: refreshed.token,
         roles: refreshed.roles,
       },
       setCookies: [
@@ -233,6 +236,7 @@ export async function ensureCookies(
             ...(refreshed.sessionId === undefined
               ? {}
               : { sessionId: refreshed.sessionId }),
+            token: refreshed.token,
             roles: refreshed.roles,
             email: refreshed.email,
             phone: refreshed.phone,
@@ -271,6 +275,7 @@ export async function ensureCookies(
         ...(typeof payload.sessionId === "string"
           ? { sessionId: payload.sessionId }
           : {}),
+        ...(typeof payload.token === "string" ? { token: payload.token } : {}),
         roles: payload.roles as string[] | undefined,
       },
     };

packages/core/src/handlers/finishLogin.ts

@@ -74,6 +74,7 @@ export async function finishLoginHandler(
         value: {
           sub: data.sub,
           ...(sessionId === undefined ? {} : { sessionId }),
+          token: data.token,
           roles: data.roles,
           email: data.email,
           phone: data.phone,

packages/core/src/handlers/finishRegister.ts

@@ -72,6 +72,7 @@ export async function finishRegisterHandler(
         value: {
           sub: data.sub,
           ...(sessionId === undefined ? {} : { sessionId }),
+          token: data.token,
           roles: data.roles,
           email: data.email,
           phone: data.phone,

packages/core/src/handlers/logout.ts

@@ -5,28 +5,44 @@ export interface LogoutOptions {
   accessCookieName: string;
   registrationCookieName: string;
   refreshCookieName: string;
+  authorization?: string;
   forwardedClientIp?: string;
+  scope?: LogoutScope;
 }
 
 export interface LogoutResult {
   status: number;
   clearCookies: string[];
 }
 
-export async function logoutHandler(
-  opts: LogoutOptions,
-): Promise<LogoutResult> {
-  await authFetch(`${opts.authServerUrl}/logout`, {
-    method: "GET",
+export type LogoutScope = "current_session" | "all_sessions";
+
+function getLogoutPath(scope: LogoutScope) {
+  return scope === "all_sessions" ? "/logout/all" : "/logout";
+}
+
+export async function logoutHandler(opts: LogoutOptions): Promise<LogoutResult> {
+  const scope = opts.scope ?? "all_sessions";
+  const upstream = await authFetch(`${opts.authServerUrl}${getLogoutPath(scope)}`, {
+    method: "DELETE",
+    authorization: opts.authorization,
     forwardedClientIp: opts.forwardedClientIp,
   });
 
   return {
-    status: 204,
+    status: upstream.ok ? 204 : upstream.status,
     clearCookies: [
       opts.accessCookieName,
       opts.registrationCookieName,
       opts.refreshCookieName,
     ],
   };
 }
+
+export function logoutCurrentSessionHandler(opts: Omit<LogoutOptions, "scope">) {
+  return logoutHandler({ ...opts, scope: "current_session" });
+}
+
+export function logoutAllSessionsHandler(opts: Omit<LogoutOptions, "scope">) {
+  return logoutHandler({ ...opts, scope: "all_sessions" });
+}

packages/core/src/handlers/oauthHandlers.ts

@@ -112,6 +112,7 @@ export async function finishOAuthLoginHandler(
         value: {
           sub: data.sub,
           ...(sessionId === undefined ? {} : { sessionId }),
+          token: data.token,
           roles: data.roles,
           email: data.email,
           phone: data.phone,

packages/core/src/handlers/pollMagicLinkConfirmationHandler.ts

@@ -89,6 +89,7 @@ export async function pollMagicLinkConfirmationHandler(
         value: {
           sub: data.sub,
           ...(sessionId === undefined ? {} : { sessionId }),
+          token: data.token,
           roles: data.roles,
           email: data.email,
           phone: data.phone,

packages/core/src/handlers/register.ts

@@ -59,7 +59,7 @@ export async function registerHandler(
     setCookies: [
       {
         name: opts.registrationCookieName,
-        value: { sub: data.sub },
+        value: { sub: data.sub, token: data.token },
         ttl: data.ttl,
         domain: opts.cookieDomain,
       },

packages/core/src/handlers/switchOrganizationHandler.ts

@@ -82,6 +82,7 @@ export async function switchOrganizationHandler(
         value: {
           sub: data.sub,
           ...(sessionId === undefined ? {} : { sessionId }),
+          token: data.token,
           roles: data.roles,
           email: data.email,
           phone: data.phone,

packages/core/src/handlers/verifyLoginOtpHandler.ts

@@ -80,6 +80,7 @@ export async function verifyLoginOtpHandler(
         value: {
           sub: data.sub,
           ...(sessionId === undefined ? {} : { sessionId }),
+          token: data.token,
           roles: data.roles,
           email: data.email,
           phone: data.phone,

packages/core/tests/ensureCookes.test.js

@@ -107,6 +107,7 @@ describe("ensureCookies", () => {
     expect(result.type).toBe("ok");
     expect(result.user?.sub).toBe("user-123");
     expect(result.user?.sessionId).toBe("session-123");
+    expect(result.user?.token).toBe("new-access");
 
     expect(result.setCookies).toHaveLength(2);
 
@@ -115,6 +116,7 @@ describe("ensureCookies", () => {
     expect(accessCookie.value).toEqual({
       sub: "user-123",
       sessionId: "session-123",
+      token: "new-access",
       roles: ["user"],
       email: "test@example.com",
       phone: "+14155552671",
@@ -209,6 +211,7 @@ describe("ensureCookies", () => {
 
     verifyCookieJwtMock.mockReturnValue({
       sub: "user-123",
+      token: "access-token",
       sessionId: "session-123",
       roles: ["user"],
     });
@@ -225,6 +228,7 @@ describe("ensureCookies", () => {
     expect(result.user).toEqual({
       sub: "user-123",
       sessionId: "session-123",
+      token: "access-token",
       roles: ["user"],
     });
   });
@@ -234,6 +238,7 @@ describe("ensureCookies", () => {
 
     verifyCookieJwtMock.mockReturnValue({
       sub: "user-123",
+      token: "access-token",
       sessionId: "session-123",
       roles: ["user"],
     });
@@ -250,6 +255,7 @@ describe("ensureCookies", () => {
     expect(result.user).toEqual({
       sub: "user-123",
       sessionId: "session-123",
+      token: "access-token",
       roles: ["user"],
     });
   });

packages/core/tests/logoutHandler.test.js

@@ -0,0 +1,59 @@
+import { jest } from "@jest/globals";
+
+const authFetchMock = jest.fn();
+
+jest.unstable_mockModule("../dist/authFetch.js", () => ({
+  authFetch: authFetchMock,
+}));
+
+const baseOptions = {
+  authServerUrl: "https://auth.example.com",
+  accessCookieName: "access",
+  registrationCookieName: "registration",
+  refreshCookieName: "refresh",
+  authorization: "Bearer service-token",
+  forwardedClientIp: "203.0.113.44",
+};
+
+describe("logoutHandler", () => {
+  beforeEach(() => authFetchMock.mockReset());
+
+  it("logs out all sessions by default for backward compatibility", async () => {
+    const { logoutHandler } = await import("../dist/handlers/logout.js");
+
+    authFetchMock.mockResolvedValue({ ok: true, status: 200 });
+
+    const result = await logoutHandler(baseOptions);
+
+    expect(authFetchMock).toHaveBeenCalledWith(
+      "https://auth.example.com/logout/all",
+      {
+        method: "DELETE",
+        authorization: "Bearer service-token",
+        forwardedClientIp: "203.0.113.44",
+      },
+    );
+    expect(result).toEqual({
+      status: 204,
+      clearCookies: ["access", "registration", "refresh"],
+    });
+  });
+
+  it("can log out only the current session", async () => {
+    const { logoutCurrentSessionHandler } = await import(
+      "../dist/handlers/logout.js"
+    );
+
+    authFetchMock.mockResolvedValue({ ok: true, status: 200 });
+
+    await logoutCurrentSessionHandler(baseOptions);
+
+    expect(authFetchMock).toHaveBeenCalledWith(
+      "https://auth.example.com/logout",
+      expect.objectContaining({
+        method: "DELETE",
+        authorization: "Bearer service-token",
+      }),
+    );
+  });
+});

packages/core/tests/oauthHandlers.test.js

@@ -104,6 +104,7 @@ describe("oauthHandlers", () => {
         value: expect.objectContaining({
           sub: "user-123",
           sessionId: "session-123",
+          token: "access-token",
           organizationId: "org-123",
         }),
       }),

packages/core/tests/registerHandler.test.js

@@ -0,0 +1,54 @@
+import { jest } from "@jest/globals";
+
+function createJsonResponse(status, body) {
+  return {
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => body,
+  };
+}
+
+describe("registerHandler", () => {
+  const originalFetch = global.fetch;
+
+  beforeEach(() => {
+    global.fetch = jest.fn();
+  });
+
+  afterEach(() => {
+    global.fetch = originalFetch;
+  });
+
+  it("stores the upstream ephemeral token in the registration cookie", async () => {
+    const { registerHandler } = await import("../dist/handlers/register.js");
+
+    global.fetch.mockResolvedValue(
+      createJsonResponse(200, {
+        message: "Success",
+        sub: "user-123",
+        token: "ephemeral-token",
+        ttl: 300,
+      }),
+    );
+
+    const result = await registerHandler(
+      {
+        body: { email: "user@example.com", phone: "+14155552671" },
+      },
+      {
+        authServerUrl: "https://auth.example.com",
+        registrationCookieName: "registration",
+      },
+    );
+
+    expect(result.status).toBe(200);
+    expect(result.setCookies).toEqual([
+      {
+        name: "registration",
+        value: { sub: "user-123", token: "ephemeral-token" },
+        ttl: 300,
+        domain: undefined,
+      },
+    ]);
+  });
+});

packages/express/README.md

@@ -142,7 +142,9 @@ Routes include:
 - `/auth/step-up/*`
 - `/auth/registration/*`
 - `/auth/users/me`
-- `/auth/logout`
+- `DELETE /auth/logout` for the current session
+- `DELETE /auth/logout/all` for every session owned by the current user
+- `GET /auth/logout` as a deprecated all-session compatibility route
 
 **Options**
 

packages/express/package.json

@@ -60,4 +60,4 @@
   "publishConfig": {
     "access": "public"
   }
-}
+}

packages/express/src/createServer.ts

@@ -317,7 +317,15 @@ export function createSeamlessAuthServer(
   );
 
   r.get("/users/me", (req, res) => me(req, res, resolvedOpts));
-  r.get("/logout", (req, res) => logout(req, res, resolvedOpts));
+  r.get("/logout", (req, res) =>
+    logout(req, res, resolvedOpts, "all_sessions"),
+  );
+  r.delete("/logout", (req, res) =>
+    logout(req, res, resolvedOpts, "current_session"),
+  );
+  r.delete("/logout/all", (req, res) =>
+    logout(req, res, resolvedOpts, "all_sessions"),
+  );
 
   r.get("/organizations", proxyWithIdentity("organizations", "access", "GET"));
   r.post("/organizations", proxyWithIdentity("organizations", "access"));

packages/express/src/handlers/logout.ts

@@ -1,21 +1,26 @@
 import { Request, Response } from "express";
 import { logoutHandler } from "@seamless-auth/core/handlers/logout";
+import type { LogoutScope } from "@seamless-auth/core/handlers/logout";
 import { clearAllCookies } from "../internal/cookie";
 import { buildForwardedClientIp } from "../internal/buildForwardedClientIp";
 import { SeamlessAuthServerOptions } from "../createServer";
+import { buildServiceAuthorization } from "../internal/buildAuthorization";
 
 export async function logout(
   req: Request,
   res: Response,
   opts: SeamlessAuthServerOptions,
+  scope: LogoutScope = "current_session",
 ) {
   const result = await logoutHandler({
     authServerUrl: opts.authServerUrl,
     accessCookieName: opts.accessCookieName!,
     registrationCookieName: opts.registrationCookieName!,
     refreshCookieName: opts.refreshCookieName!,
+    authorization: buildServiceAuthorization(req, opts),
     forwardedClientIp: buildForwardedClientIp(req),
-  } as any);
+    scope,
+  });
 
   clearAllCookies(res, opts.cookieDomain || "", ...result.clearCookies);