@luckystack/login 0.1.7 → 0.1.9

package/CHANGELOG.md

@@ -1,14 +1,14 @@
-# Changelog
-
-All notable changes to `@luckystack/login` are documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [0.1.0]
-
-### Added
-
-- Initial public release as part of the LuckyStack package split.
+# Changelog
+
+All notable changes to `@luckystack/login` are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0]
+
+### Added
+
+- Initial public release as part of the LuckyStack package split.

package/CLAUDE.md

@@ -138,7 +138,7 @@ All config keys live on `ProjectConfig` (from `@luckystack/core`). Resolved at c
 | `FACEBOOK_CLIENT_ID` / `FACEBOOK_CLIENT_SECRET` | `facebookProvider` | OAuth app credentials. |
 | `MICROSOFT_CLIENT_ID` / `MICROSOFT_CLIENT_SECRET` | `microsoftProvider` | OAuth app credentials. |
 | `MICROSOFT_TENANT_ID` | `microsoftProvider` (optional) | Single-tenant Azure AD. Defaults to `'common'`. |
-| `DNS` | All OAuth `callbackUrl` builders | Base URL prepended to `/auth/callback/<provider>`. |
+| (callback origin) | All OAuth `callbackUrl` builders | The `callbackUrl` is the BACKEND origin + `/auth/callback/<provider>`. The scaffold derives it in `config.ts` (`oauthCallbackBase`: dev `http://localhost:80`, prod the public domain). No `DNS` env var — that was removed in 0.1.5. |
 | `BCRYPT_ROUNDS` | `auth.bcryptRounds` | Surfaced through project config; salt rounds for credentials hashing. |
 
 > Env-key set without the matching package installed = hard boot crash (see peer-dep guard policy). `@luckystack/email` is the optional case — login lazy-imports it and gracefully fails when `forgotPassword !== 'framework'`.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Mathijs van Melick
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Mathijs van Melick
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -57,12 +57,12 @@ registerOAuthProviders([
   googleProvider({
     clientId: process.env.GOOGLE_CLIENT_ID,
     clientSecret: process.env.GOOGLE_CLIENT_SECRET,
-    callbackUrl: `${process.env.DNS}/auth/callback/google`,
+    callbackUrl: `http://localhost:80/auth/callback/google`,
   }),
   githubProvider({
     clientId: process.env.GITHUB_CLIENT_ID,
     clientSecret: process.env.GITHUB_CLIENT_SECRET,
-    callbackUrl: `${process.env.DNS}/auth/callback/github`,
+    callbackUrl: `http://localhost:80/auth/callback/github`,
   }),
 ]);
 ```
@@ -77,7 +77,7 @@ Every helper accepts the base shape plus optional overrides for self-hosted inst
 | --- | --- | --- | --- |
 | `clientId` | all | — | Required. The OAuth app's client identifier. |
 | `clientSecret` | all | — | Required. The OAuth app's client secret. |
-| `callbackUrl` | all | — | Required. Must match the URL registered with the provider, normally `${DNS}/auth/callback/<name>`. |
+| `callbackUrl` | all | — | Required. Must match the URL registered with the provider — your BACKEND origin + `/auth/callback/<name>` (dev `http://localhost:80/auth/callback/<name>`, prod `https://your-domain.com/auth/callback/<name>`). |
 | `endpoints?.authorizationURL` | all | provider-default | GitHub Enterprise host, Microsoft custom-tenant authorize URL, internal auth proxy, etc. |
 | `endpoints?.tokenExchangeURL` | all | provider-default | Same use cases as `authorizationURL`. |
 | `endpoints?.userInfoURL` | all | provider-default | Self-hosted GitHub Enterprise / Microsoft Graph mirror, etc. |
@@ -91,7 +91,7 @@ Example — self-hosted GitHub Enterprise:
 githubProvider({
   clientId: process.env.GITHUB_CLIENT_ID,
   clientSecret: process.env.GITHUB_CLIENT_SECRET,
-  callbackUrl: `${process.env.DNS}/auth/callback/github`,
+  callbackUrl: `http://localhost:80/auth/callback/github`,
   endpoints: {
     authorizationURL: 'https://github.acme.example/login/oauth/authorize',
     tokenExchangeURL: 'https://github.acme.example/login/oauth/access_token',
@@ -106,7 +106,7 @@ Example — single-tenant Microsoft Entra ID:
 microsoftProvider({
   clientId: process.env.MICROSOFT_CLIENT_ID,
   clientSecret: process.env.MICROSOFT_CLIENT_SECRET,
-  callbackUrl: `${process.env.DNS}/auth/callback/microsoft`,
+  callbackUrl: `http://localhost:80/auth/callback/microsoft`,
   tenant: process.env.MICROSOFT_TENANT_ID, // 'common' for any tenant; UUID for a single tenant.
   apiVersion: 'v2.0',                       // OAuth endpoint version
   graphApiVersion: 'v1.0',                  // Graph endpoint version

package/dist/index.d.ts

@@ -137,8 +137,20 @@ declare module '@luckystack/core' {
  * @param token - The session token (unique identifier)
  * @param data - The session data to store
  * @param newUser - If true, this is a new login (triggers single-session enforcement)
+ * @param options.supersedeToken - A token belonging to the SAME browser that is
+ *   being replaced by this login (e.g. re-login while already signed in). It is
+ *   excluded from single-session enforcement so the user's current device is not
+ *   kicked by its own new session. The caller is responsible for deleting it
+ *   afterwards (use `deleteSession(supersedeToken, { skipSocketLogout: true })`).
  */
-declare const saveSession: (token: string, data: BaseSessionLayout, newUser?: boolean) => Promise<void>;
+declare const saveSession: (token: string, data: BaseSessionLayout, newUser?: boolean, options?: {
+    supersedeToken?: string;
+}) => Promise<{
+    ok: true;
+} | {
+    ok: false;
+    errorCode: string;
+}>;
 /**
  * Retrieve a user session through the active session adapter.
  *
@@ -151,9 +163,16 @@ declare const getSession: (token: string | null) => Promise<BaseSessionLayout |
  * clients.
  *
  * @param token - The session token to delete
+ * @param options.skipSocketLogout - When true, the session data + active-token
+ *   tracking are cleaned up and the pre/post delete hooks still fire, but NO
+ *   `logout` is emitted to sockets in the token's room. Use this when the SAME
+ *   browser is replacing its session (re-login): emitting a logout would bounce
+ *   that browser to the login page and null its brand-new session.
  * @returns true if successful
  */
-declare const deleteSession: (token: string) => Promise<boolean>;
+declare const deleteSession: (token: string, options?: {
+    skipSocketLogout?: boolean;
+}) => Promise<boolean>;
 /**
  * Get all active sessions (admin utility). Returns empty when the active
  * adapter doesn't implement enumeration (signed-JWT-stateless, log-only).
@@ -283,6 +302,8 @@ declare const registerWithCredentials: ({ email, password, name, confirmPassword
 declare const loginWithCredentialsCore: ({ email, password }: {
     email: string;
     password: string;
+}, options?: {
+    supersedeToken?: string;
 }) => Promise<{
     status: boolean;
     reason: string;
@@ -299,7 +320,9 @@ declare const loginWithCredentialsCore: ({ email, password }: {
     newToken: string;
     session: BaseSessionLayout;
 }>;
-declare const loginWithCredentials: (params: paramsType) => Promise<{
+declare const loginWithCredentials: (params: paramsType, options?: {
+    supersedeToken?: string;
+}) => Promise<{
     status: false;
     reason: string;
 } | {
@@ -330,6 +353,7 @@ interface OAuthCallbackResult {
 }
 declare const loginCallback: (pathname: string, req: IncomingMessage, _res: ServerResponse, options?: {
     defaultRedirectUrl?: string;
+    supersedeToken?: string;
 }) => Promise<OAuthCallbackResult | false>;
 
 declare const logout: ({ token, socket, userId, skipSessionDelete }: {

package/dist/index.js

@@ -169,8 +169,8 @@ var init_session = __esm({
       const parsed = JSON.parse(value);
       return isSessionLayout(parsed) ? parsed : null;
     };
-    saveSession = async (token, data, newUser) => {
-      const [error] = await tryCatch3(async () => {
+    saveSession = async (token, data, newUser, options) => {
+      const [error, outcome] = await tryCatch3(async () => {
         const adapter = getSessionAdapter();
         if (newUser) {
           const preSessionCreateResult = await dispatchHook2("preSessionCreate", {
@@ -180,7 +180,7 @@ var init_session = __esm({
           });
           if (preSessionCreateResult.stopped) {
             getLogger2().warn(`session create aborted by preSessionCreate hook`, { errorCode: preSessionCreateResult.signal.errorCode });
-            return;
+            return { ok: false, errorCode: preSessionCreateResult.signal.errorCode || "api.internalServerError" };
           }
         }
         data.csrfToken ??= randomBytes(getCsrfConfig().tokenLength).toString("hex");
@@ -192,13 +192,15 @@ var init_session = __esm({
         }
         const { getIoInstance } = await import("@luckystack/core");
         const io = getIoInstance();
-        if (!io) return;
+        if (!io) return { ok: true };
         if (newUser && userId) {
           const sessionCfg = getProjectConfig().session;
           const effectivePerUser = sessionCfg.allowMultiple ? "multiple" : sessionCfg.perUser;
           const cap = sessionCfg.maxConcurrentPerUser;
           const allTokens = await adapter.listActive(userId);
-          const previousTokens = allTokens.filter((t) => t !== token);
+          const previousTokens = allTokens.filter(
+            (t) => t !== token && t !== options?.supersedeToken
+          );
           let tokensToKick = [];
           if (effectivePerUser === "single") {
             tokensToKick = previousTokens;
@@ -237,10 +239,13 @@ var init_session = __esm({
         if (newUser) {
           await dispatchHook2("postSessionCreate", { token, user: data, persistent: !getProjectConfig().session.basedToken });
         }
+        return { ok: true };
       }, void 0, { fn: "saveSession", token });
       if (error) {
         getLogger2().error("saveSession failed", error, { token });
+        return { ok: false, errorCode: "api.internalServerError" };
       }
+      return outcome ?? { ok: false, errorCode: "api.internalServerError" };
     };
     getSession = async (token) => {
       if (!token) return null;
@@ -274,7 +279,7 @@ var init_session = __esm({
       }
       return value;
     };
-    deleteSession = async (token) => {
+    deleteSession = async (token, options) => {
       if (process.env.LUCKYSTACK_TRACE_SESSION_DELETES === "1") {
         getLogger2().warn("[session] deleteSession invoked", {
           tokenPrefix: token.slice(0, 8),
@@ -296,7 +301,7 @@ var init_session = __esm({
         if (raw && resolvedUserId) {
           const { getIoInstance } = await import("@luckystack/core");
           const ioInstance = getIoInstance();
-          if (ioInstance) {
+          if (ioInstance && !options?.skipSocketLogout) {
             const { logout: logout2 } = await Promise.resolve().then(() => (init_logout(), logout_exports));
             const sockets = ioInstance.sockets.adapter.rooms.get(token);
             if (sockets) {
@@ -968,7 +973,7 @@ var registerWithCredentials = async ({
     session: sanitizeUserForSession(createNewUserResponse)
   };
 };
-var loginWithCredentialsCore = async ({ email, password }) => {
+var loginWithCredentialsCore = async ({ email, password }, options) => {
   const preLoginResult = await dispatchHook3("preLogin", { email, provider: "credentials" });
   if (preLoginResult.stopped) {
     return { status: false, reason: preLoginResult.signal.errorCode };
@@ -1004,14 +1009,17 @@ var loginWithCredentialsCore = async ({ email, password }) => {
   if (existsSync(filePath)) {
     newUser.avatar = `${newUser.id}.webp`;
   }
-  await saveSession(newToken, newUser, true);
+  const saved = await saveSession(newToken, newUser, true, { supersedeToken: options?.supersedeToken });
+  if (!saved.ok) {
+    return { status: false, reason: saved.errorCode };
+  }
   await dispatchHook3("postLogin", { userId: newUser.id, provider: "credentials", isNewUser: false, token: newToken });
   if (isDevMode()) {
     getLogger3().debug(`credentials login success for user ${newUser.id}`);
   }
   return { status: true, reason: "login.loggedIn", newToken, session: newUser };
 };
-var loginWithCredentials = async (params) => {
+var loginWithCredentials = async (params, options) => {
   const creds = normalizeCredentials(params);
   if (isDevMode()) {
     getLogger3().debug(`credentials auth attempt for ${creds.email || "unknown-email"}`);
@@ -1026,7 +1034,7 @@ var loginWithCredentials = async (params) => {
       confirmPassword: creds.confirmPassword
     });
   }
-  return loginWithCredentialsCore({ email: creds.email, password: creds.password });
+  return loginWithCredentialsCore({ email: creds.email, password: creds.password }, options);
 };
 var isAllowedRedirectUrl = (url) => {
   if (!URL.canParse(url, "http://placeholder")) return false;
@@ -1249,7 +1257,11 @@ var loginCallback = async (pathname, req, _res, options = {}) => {
       Object.assign(resolved.user, extra);
     }
   }
-  await saveSession(newToken, resolved.user, true);
+  const saved = await saveSession(newToken, resolved.user, true, { supersedeToken: options.supersedeToken });
+  if (!saved.ok) {
+    getLogger3().error(`[oauth:${providerName}] saveSession failed \u2014 aborting callback`, { errorCode: saved.errorCode });
+    return false;
+  }
   if (resolved.isNewUser) {
     await dispatchHook3("postRegister", { userId: resolved.user.id, provider: providerName });
   }