@atlasauth/js 0.17.0 → 0.18.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @atlasauth/js changelog
 
+## 0.18.0 — 2026-10-24
+
+### Added
+
+- Better Auth session bridge for apps whose Better Auth cookie is readable by script: exchanges it once for an Atlas session.
+
 ## 0.17.0 — 2026-10-24
 
 ### Added

package/dist/better-auth-bridge.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Moving from Better Auth, browser side: exchange the visitor's Better Auth
+ * session for an Atlas session, once, so the switch signs nobody out.
+ *
+ * Only for apps whose Better Auth session cookie is readable by script (the old
+ * app turned `httpOnly` off). Better Auth's default cookie is HttpOnly — then the
+ * exchange belongs on your server: the Next.js middleware's `betterAuthBridge`,
+ * or the Express / Fastify / Hono adapters' option of the same name.
+ *
+ * The call goes to `POST /v1/client/migrations/better_auth/exchange` with cookie
+ * delivery: on success Atlas sets its session cookies exactly as a sign-in does,
+ * and the Better Auth cookies are cleared from this page. A user who still owes
+ * a second factor gets the sign-in attempt to continue
+ * (`attemptId` + `status`, the same continuation a redirect sign-in carries).
+ */
+import type { FapiClient } from './fapi';
+export declare const BETTER_AUTH_EXCHANGE_PATH = "/v1/client/migrations/better_auth/exchange";
+export interface BetterAuthExchangeInput {
+    /** The Better Auth session cookie value. Default: read from `document.cookie`. */
+    token?: string;
+    /** Better Auth's `advanced.cookiePrefix` (default `better-auth`). */
+    cookiePrefix?: string;
+    /** The session cookie's full name, when the old app overrode it. */
+    cookieName?: string;
+    /** false → the Atlas refresh cookie lasts only for this browser session. */
+    remember?: boolean;
+    /** Where to read/clear cookies. Default: `document`. */
+    document?: {
+        cookie: string;
+    };
+}
+export type BetterAuthExchangeOutcome = 
+/** No Better Auth session cookie here: nothing to do. */
+{
+    status: 'none';
+}
+/** Signed in: Atlas set its session cookies. Reload your Atlas client (or the page). */
+ | {
+    status: 'complete';
+    sessionId: string;
+    userId: string;
+    jwt: string;
+}
+/** A second factor (or MFA enrolment) is owed: continue the attempt with your sign-in UI. */
+ | {
+    status: 'needs_second_factor' | 'needs_mfa_enrollment';
+    attemptId: string;
+}
+/** Refused. `outcome` is Atlas's `bridge_outcome` (`invalid`, `expired`, `reused`, `closed`, …) or `error`. */
+ | {
+    status: 'refused';
+    outcome: string;
+};
+/** The readable Better Auth session cookie value, or undefined. */
+export declare function readBetterAuthCookie(input?: BetterAuthExchangeInput): string | undefined;
+/** Expire the Better Auth cookies this page can reach. */
+export declare function clearBetterAuthCookies(input?: BetterAuthExchangeInput): void;
+/**
+ * Exchange the Better Auth session (read from the page, or `input.token`) for
+ * an Atlas session. Never throws.
+ */
+export declare function exchangeBetterAuthSession(client: FapiClient, input?: BetterAuthExchangeInput): Promise<BetterAuthExchangeOutcome>;

package/dist/better-auth-bridge.js

@@ -0,0 +1,83 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BETTER_AUTH_EXCHANGE_PATH = void 0;
+exports.readBetterAuthCookie = readBetterAuthCookie;
+exports.clearBetterAuthCookies = clearBetterAuthCookies;
+exports.exchangeBetterAuthSession = exchangeBetterAuthSession;
+exports.BETTER_AUTH_EXCHANGE_PATH = '/v1/client/migrations/better_auth/exchange';
+const DEFAULT_PREFIX = 'better-auth';
+function cookieNames(input) {
+    const prefix = input.cookiePrefix ?? DEFAULT_PREFIX;
+    const session = input.cookieName ?? `${prefix}.session_token`;
+    const base = [session, `${prefix}.session_data`, `${prefix}.account_data`, `${prefix}.dont_remember`];
+    return { session: [`__Secure-${session}`, session], all: [...base.map((n) => `__Secure-${n}`), ...base] };
+}
+function readCookie(header, name) {
+    for (const part of header.split(';')) {
+        const [key, ...rest] = part.trim().split('=');
+        if (key === name)
+            return rest.join('=');
+    }
+    return undefined;
+}
+/** The readable Better Auth session cookie value, or undefined. */
+function readBetterAuthCookie(input = {}) {
+    const doc = input.document ?? (typeof document !== 'undefined' ? document : undefined);
+    if (!doc)
+        return undefined;
+    for (const name of cookieNames(input).session) {
+        const value = readCookie(doc.cookie, name);
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+/** Expire the Better Auth cookies this page can reach. */
+function clearBetterAuthCookies(input = {}) {
+    const doc = input.document ?? (typeof document !== 'undefined' ? document : undefined);
+    if (!doc)
+        return;
+    for (const name of cookieNames(input).all) {
+        doc.cookie = `${name}=; Path=/; Max-Age=0${name.startsWith('__Secure-') ? '; Secure' : ''}`;
+    }
+}
+/** Refusals after which the Better Auth session will never exchange: its cookies are cleared. */
+const FINAL = new Set(['invalid', 'signature_invalid', 'expired', 'reused', 'user_unavailable']);
+/**
+ * Exchange the Better Auth session (read from the page, or `input.token`) for
+ * an Atlas session. Never throws.
+ */
+async function exchangeBetterAuthSession(client, input = {}) {
+    const token = input.token ?? readBetterAuthCookie(input);
+    if (!token)
+        return { status: 'none' };
+    let response;
+    try {
+        response = await client.post(exports.BETTER_AUTH_EXCHANGE_PATH, {
+            token,
+            delivery: 'cookie',
+            ...(input.remember === false ? { remember: false } : {}),
+        });
+    }
+    catch {
+        return { status: 'refused', outcome: 'error' };
+    }
+    const data = response.data;
+    if (response.ok && data?.object === 'session' && data.id && data.jwt) {
+        clearBetterAuthCookies(input);
+        return { status: 'complete', sessionId: data.id, userId: data.user_id ?? '', jwt: data.jwt };
+    }
+    if (response.ok &&
+        data?.object === 'sign_in_attempt' &&
+        data.id &&
+        (data.status === 'needs_second_factor' || data.status === 'needs_mfa_enrollment')) {
+        clearBetterAuthCookies(input);
+        return { status: data.status, attemptId: data.id };
+    }
+    const outcome = response.errors[0]?.meta?.bridge_outcome;
+    const reason = typeof outcome === 'string' ? outcome : 'error';
+    if (FINAL.has(reason))
+        clearBetterAuthCookies(input);
+    return { status: 'refused', outcome: reason };
+}
+//# sourceMappingURL=better-auth-bridge.js.map

package/dist/better-auth-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"better-auth-bridge.js","sourceRoot":"","sources":["../src/better-auth-bridge.ts"],"names":[],"mappings":";;;AA2DA,oDAQC;AAGD,wDAMC;AASD,8DA0CC;AA9GY,QAAA,yBAAyB,GAAG,4CAA4C,CAAC;AACtF,MAAM,cAAc,GAAG,aAAa,CAAC;AAyBrC,SAAS,WAAW,CAAC,KAA8B;IACjD,MAAM,MAAM,GAAG,KAAK,CAAC,YAAY,IAAI,cAAc,CAAC;IACpD,MAAM,OAAO,GAAG,KAAK,CAAC,UAAU,IAAI,GAAG,MAAM,gBAAgB,CAAC;IAC9D,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,GAAG,MAAM,eAAe,EAAE,GAAG,MAAM,eAAe,EAAE,GAAG,MAAM,gBAAgB,CAAC,CAAC;IACtG,OAAO,EAAE,OAAO,EAAE,CAAC,YAAY,OAAO,EAAE,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;AAC5G,CAAC;AAED,SAAS,UAAU,CAAC,MAAc,EAAE,IAAY;IAC9C,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9C,IAAI,GAAG,KAAK,IAAI;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC1C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,mEAAmE;AACnE,SAAgB,oBAAoB,CAAC,QAAiC,EAAE;IACtE,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,IAAI,CAAC,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACvF,IAAI,CAAC,GAAG;QAAE,OAAO,SAAS,CAAC;IAC3B,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;QAC9C,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC3C,IAAI,KAAK;YAAE,OAAO,KAAK,CAAC;IAC1B,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,0DAA0D;AAC1D,SAAgB,sBAAsB,CAAC,QAAiC,EAAE;IACxE,MAAM,GAAG,GAAG,KAAK,CAAC,QAAQ,IAAI,CAAC,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IACvF,IAAI,CAAC,GAAG;QAAE,OAAO;IACjB,KAAK,MAAM,IAAI,IAAI,WAAW,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,CAAC;QAC1C,GAAG,CAAC,MAAM,GAAG,GAAG,IAAI,uBAAuB,IAAI,CAAC,UAAU,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;IAC9F,CAAC;AACH,CAAC;AAED,iGAAiG;AACjG,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,mBAAmB,EAAE,SAAS,EAAE,QAAQ,EAAE,kBAAkB,CAAC,CAAC,CAAC;AAEjG;;;GAGG;AACI,KAAK,UAAU,yBAAyB,CAC7C,MAAkB,EAClB,QAAiC,EAAE;IAEnC,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,IAAI,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACzD,IAAI,CAAC,KAAK;QAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAEtC,IAAI,QAAQ,CAAC;IACb,IAAI,CAAC;QACH,QAAQ,GAAG,MAAM,MAAM,CAAC,IAAI,CAMzB,iCAAyB,EAAE;YAC5B,KAAK;YACL,QAAQ,EAAE,QAAQ;YAClB,GAAG,CAAC,KAAK,CAAC,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzD,CAAC,CAAC;IACL,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC;IACjD,CAAC;IAED,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC;IAC3B,IAAI,QAAQ,CAAC,EAAE,IAAI,IAAI,EAAE,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,GAAG,EAAE,CAAC;QACrE,sBAAsB,CAAC,KAAK,CAAC,CAAC;QAC9B,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC;IAC/F,CAAC;IACD,IACE,QAAQ,CAAC,EAAE;QACX,IAAI,EAAE,MAAM,KAAK,iBAAiB;QAClC,IAAI,CAAC,EAAE;QACP,CAAC,IAAI,CAAC,MAAM,KAAK,qBAAqB,IAAI,IAAI,CAAC,MAAM,KAAK,sBAAsB,CAAC,EACjF,CAAC;QACD,sBAAsB,CAAC,KAAK,CAAC,CAAC;QAC9B,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,CAAC,EAAE,EAAE,CAAC;IACrD,CAAC;IACD,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC;IACzD,MAAM,MAAM,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC;IAC/D,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC;QAAE,sBAAsB,CAAC,KAAK,CAAC,CAAC;IACrD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC;AAChD,CAAC"}

package/dist/index.d.ts

@@ -38,6 +38,7 @@ export * from './profile';
 export * from './connect';
 export * from './password-reset';
 export * from './check-session';
+export * from './better-auth-bridge';
 export * from './frontchannel-logout';
 export * from './upstream-logout';
 export * from './captcha';

package/dist/index.js

@@ -82,6 +82,8 @@ __exportStar(require("./profile"), exports);
 __exportStar(require("./connect"), exports);
 __exportStar(require("./password-reset"), exports);
 __exportStar(require("./check-session"), exports);
+// Moving from Better Auth: exchange a readable Better Auth session cookie for an Atlas session.
+__exportStar(require("./better-auth-bridge"), exports);
 // OIDC Front-Channel Logout after a browser sign-out.
 __exportStar(require("./frontchannel-logout"), exports);
 // RP-initiated logout at an upstream OpenID provider after a browser sign-out.

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,6EAA6E;AAC7E,2CAAyB;AACzB,6CAA2B;AAC3B,yDAAyD;AACzD,kDAAgC;AAChC,sFAAsF;AACtF,mDAAiC;AACjC,gDAA8B;AAC9B,iDAA+B;AAC/B,4CAA0B;AAC1B,iDAA+B;AAC/B,kDAAgC;AAChC,uEAAuE;AACvE,2CAAyB;AACzB,6CAA2B;AAC3B,qFAAqF;AACrF,kDAAgC;AAChC,yCAAuB;AACvB,mGAAmG;AACnG,2DAAyC;AACzC,+EAA+E;AAC/E,6CAA2B;AAC3B,gGAAgG;AAChG,6CAA0G;AAAjG,gHAAA,iBAAiB,OAAA;AAAE,8GAAA,eAAe,OAAA;AAAE,oHAAA,qBAAqB,OAAA;AAAE,6GAAA,cAAc,OAAA;AAClF,qDAW2B;AAVzB,oHAAA,iBAAiB,OAAA;AACjB,2HAAA,wBAAwB,OAAA;AACxB,oHAAA,iBAAiB,OAAA;AACjB,gHAAA,aAAa,OAAA;AACb,wHAAA,qBAAqB,OAAA;AACrB,uHAAA,oBAAoB,OAAA;AAMtB,iEAAiE;AACjE,iDAA+B;AAC/B,4CAA0B;AAC1B,yFAAyF;AACzF,oDAAkC;AAClC,2CAAyB;AACzB,mDAAiC;AACjC,4CAA0B;AAC1B,0GAA0G;AAC1G,mDAAiC;AACjC,uFAAuF;AACvF,oDAAkC;AAClC,4EAA4E;AAC5E,oDAAkC;AAClC,sGAAsG;AACtG,qDAAmC;AACnC,6CAA2B;AAC3B,yCAAuB;AACvB,8CAA4B;AAC5B,2CAAyB;AACzB,4DAA4D;AAC5D,6CAA2B;AAC3B,yDAAuC;AACvC,kDAAgC;AAChC,kDAAgC;AAChC,+DAA+D;AAC/D,kDAAgC;AAChC,qEAAqE;AACrE,4CAA0B;AAC1B,4CAA0B;AAC1B,mDAAiC;AACjC,kDAAgC;AAChC,sDAAsD;AACtD,wDAAsC;AACtC,+EAA+E;AAC/E,oDAAkC;AAClC,+EAA+E;AAC/E,2EAA2E;AAC3E,4CAA0B;AAC1B,kFAAkF;AAClF,mDAAiC;AACjC,4FAA4F;AAC5F,kDAAgC;AAChC,kFAAkF;AAClF,yEAAyE;AACzE,oEAAoE;AACpE,uDAAqC;AACrC,sDAAoC;AACpC,uEAAuE;AACvE,gDAA8B;AAC9B,0EAA0E;AAC1E,4EAA4E;AAC5E,0CAa0B;AARxB,iGAAA,QAAQ,OAAA;AACR,sGAAA,aAAa,OAAA;AACb,0GAAA,iBAAiB,OAAA;AACjB,uGAAA,cAAc,OAAA;AACd,yGAAA,gBAAgB,OAAA;AAChB,+GAAA,sBAAsB,OAAA;AACtB,kGAAA,SAAS,OAAA;AACT,wGAAA,eAAe,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,6EAA6E;AAC7E,2CAAyB;AACzB,6CAA2B;AAC3B,yDAAyD;AACzD,kDAAgC;AAChC,sFAAsF;AACtF,mDAAiC;AACjC,gDAA8B;AAC9B,iDAA+B;AAC/B,4CAA0B;AAC1B,iDAA+B;AAC/B,kDAAgC;AAChC,uEAAuE;AACvE,2CAAyB;AACzB,6CAA2B;AAC3B,qFAAqF;AACrF,kDAAgC;AAChC,yCAAuB;AACvB,mGAAmG;AACnG,2DAAyC;AACzC,+EAA+E;AAC/E,6CAA2B;AAC3B,gGAAgG;AAChG,6CAA0G;AAAjG,gHAAA,iBAAiB,OAAA;AAAE,8GAAA,eAAe,OAAA;AAAE,oHAAA,qBAAqB,OAAA;AAAE,6GAAA,cAAc,OAAA;AAClF,qDAW2B;AAVzB,oHAAA,iBAAiB,OAAA;AACjB,2HAAA,wBAAwB,OAAA;AACxB,oHAAA,iBAAiB,OAAA;AACjB,gHAAA,aAAa,OAAA;AACb,wHAAA,qBAAqB,OAAA;AACrB,uHAAA,oBAAoB,OAAA;AAMtB,iEAAiE;AACjE,iDAA+B;AAC/B,4CAA0B;AAC1B,yFAAyF;AACzF,oDAAkC;AAClC,2CAAyB;AACzB,mDAAiC;AACjC,4CAA0B;AAC1B,0GAA0G;AAC1G,mDAAiC;AACjC,uFAAuF;AACvF,oDAAkC;AAClC,4EAA4E;AAC5E,oDAAkC;AAClC,sGAAsG;AACtG,qDAAmC;AACnC,6CAA2B;AAC3B,yCAAuB;AACvB,8CAA4B;AAC5B,2CAAyB;AACzB,4DAA4D;AAC5D,6CAA2B;AAC3B,yDAAuC;AACvC,kDAAgC;AAChC,kDAAgC;AAChC,+DAA+D;AAC/D,kDAAgC;AAChC,qEAAqE;AACrE,4CAA0B;AAC1B,4CAA0B;AAC1B,mDAAiC;AACjC,kDAAgC;AAChC,gGAAgG;AAChG,uDAAqC;AACrC,sDAAsD;AACtD,wDAAsC;AACtC,+EAA+E;AAC/E,oDAAkC;AAClC,+EAA+E;AAC/E,2EAA2E;AAC3E,4CAA0B;AAC1B,kFAAkF;AAClF,mDAAiC;AACjC,4FAA4F;AAC5F,kDAAgC;AAChC,kFAAkF;AAClF,yEAAyE;AACzE,oEAAoE;AACpE,uDAAqC;AACrC,sDAAoC;AACpC,uEAAuE;AACvE,gDAA8B;AAC9B,0EAA0E;AAC1E,4EAA4E;AAC5E,0CAa0B;AARxB,iGAAA,QAAQ,OAAA;AACR,sGAAA,aAAa,OAAA;AACb,0GAAA,iBAAiB,OAAA;AACjB,uGAAA,cAAc,OAAA;AACd,yGAAA,gBAAgB,OAAA;AAChB,+GAAA,sBAAsB,OAAA;AACtB,kGAAA,SAAS,OAAA;AACT,wGAAA,eAAe,OAAA"}

package/dist/version.d.ts

@@ -4,4 +4,4 @@
  * package.json at runtime) so the bundle stays dependency-free and tests stay
  * deterministic; `version.test.ts` fails when it drifts from package.json.
  */
-export declare const ATLAS_JS_VERSION = "0.17.0";
+export declare const ATLAS_JS_VERSION = "0.18.0";

package/dist/version.js

@@ -7,5 +7,5 @@ exports.ATLAS_JS_VERSION = void 0;
  * package.json at runtime) so the bundle stays dependency-free and tests stay
  * deterministic; `version.test.ts` fails when it drifts from package.json.
  */
-exports.ATLAS_JS_VERSION = '0.17.0';
+exports.ATLAS_JS_VERSION = '0.18.0';
 //# sourceMappingURL=version.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlasauth/js",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {