@atlasauth/js 0.5.0 → 0.7.0

package/dist/index.js

@@ -15,10 +15,15 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.isPermissionKey = exports.isRoleKey = exports.PERMISSION_KEY_PATTERN = exports.ROLE_KEY_PATTERN = exports.ForbiddenError = exports.protectFromClaims = exports.hasFromClaims = exports.evaluate = void 0;
+// Provider configuration checks (frontendApi) shared by every framework SDK.
+__exportStar(require("./config"), exports);
+__exportStar(require("./sign-out"), exports);
 __exportStar(require("./token-cache"), exports);
 __exportStar(require("./tab-election"), exports);
 __exportStar(require("./attempt"), exports);
 __exportStar(require("./redirect"), exports);
+// §oauth popup mode: the same-origin hand-back for a popup whose opener was severed.
+__exportStar(require("./popup-channel"), exports);
 __exportStar(require("./fapi"), exports);
 __exportStar(require("./native"), exports);
 __exportStar(require("./native-session"), exports);
@@ -27,6 +32,8 @@ __exportStar(require("./telegram"), exports);
 __exportStar(require("./siwe"), exports);
 __exportStar(require("./telemetry"), exports);
 __exportStar(require("./reauth"), exports);
+// End-user API key self-service (`/v1/client/me/api_keys`).
+__exportStar(require("./api-keys"), exports);
 __exportStar(require("./connect"), exports);
 __exportStar(require("./password-reset"), exports);
 __exportStar(require("./check-session"), exports);
@@ -35,6 +42,13 @@ __exportStar(require("./frontchannel-logout"), exports);
 // §5 "captcha anywhere" — fetch the central widget config, render the provider
 // widget, and verify a solved token, all without hardcoding provider keys.
 __exportStar(require("./captcha"), exports);
+// Per-flow captcha widget rendering shared by the prebuilt sign-in / sign-up UIs.
+__exportStar(require("./captcha-widget"), exports);
+// The framework-agnostic captcha lifecycle + sign-in / sign-up submit helpers the
+// prebuilt forms of every framework SDK share, and the instance's public
+// sign-in / sign-up settings (`/v1/appearance`) they are driven by.
+__exportStar(require("./captcha-controller"), exports);
+__exportStar(require("./instance-settings"), exports);
 // Framework-agnostic authorization primitive — `has()`/`evaluate` for any
 // non-React/Next consumer reading org_role/org_permissions off its session.
 var authz_1 = require("@atlasauth/authz");

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA,gDAA8B;AAC9B,iDAA+B;AAC/B,4CAA0B;AAC1B,6CAA2B;AAC3B,yCAAuB;AACvB,2CAAyB;AACzB,mDAAiC;AACjC,4CAA0B;AAC1B,6CAA2B;AAC3B,yCAAuB;AACvB,8CAA4B;AAC5B,2CAAyB;AACzB,4CAA0B;AAC1B,mDAAiC;AACjC,kDAAgC;AAChC,sDAAsD;AACtD,wDAAsC;AACtC,+EAA+E;AAC/E,2EAA2E;AAC3E,4CAA0B;AAC1B,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,gDAA8B;AAC9B,iDAA+B;AAC/B,4CAA0B;AAC1B,6CAA2B;AAC3B,qFAAqF;AACrF,kDAAgC;AAChC,yCAAuB;AACvB,2CAAyB;AACzB,mDAAiC;AACjC,4CAA0B;AAC1B,6CAA2B;AAC3B,yCAAuB;AACvB,8CAA4B;AAC5B,2CAAyB;AACzB,4DAA4D;AAC5D,6CAA2B;AAC3B,4CAA0B;AAC1B,mDAAiC;AACjC,kDAAgC;AAChC,sDAAsD;AACtD,wDAAsC;AACtC,+EAA+E;AAC/E,2EAA2E;AAC3E,4CAA0B;AAC1B,kFAAkF;AAClF,mDAAiC;AACjC,kFAAkF;AAClF,yEAAyE;AACzE,oEAAoE;AACpE,uDAAqC;AACrC,sDAAoC;AACpC,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/instance-settings.d.ts

@@ -0,0 +1,58 @@
+import type { CaptchaFlowKey, FlowCaptcha } from './captcha-widget';
+import type { FapiClient } from './fapi';
+/**
+ * The instance's public sign-in / sign-up settings, read from
+ * `GET /v1/appearance`. Public data only — the captcha provider + site key +
+ * render mode per flow, the extra fields the create-account form collects, and
+ * the legal-consent policy. The prebuilt sign-in / sign-up components of every
+ * framework SDK read it so that turning a setting on in the dashboard (e.g.
+ * captcha on sign-up) takes effect with no code change.
+ */
+export interface InstanceSettings {
+    /** Per-flow captcha (`{ enabled: false }` when a flow draws nothing). */
+    captchaFlows: Partial<Record<CaptchaFlowKey, FlowCaptcha>>;
+    /** Extra fields the create-account form collects, in display order. */
+    signUpFields: PublicSignUpField[];
+    /** Terms / privacy links and whether agreement is required on sign-up. */
+    legal: {
+        termsUrl: string | null;
+        privacyUrl: string | null;
+        required: boolean;
+    };
+}
+/** One configurable sign-up field, exactly as `/v1/appearance` resolves it. */
+export interface PublicSignUpField {
+    key: string;
+    label: string;
+    type: 'text' | 'email' | 'tel' | 'url' | 'number' | 'date' | 'textarea' | 'checkbox' | 'select' | 'radio' | 'multiselect';
+    required: boolean;
+    placeholder: string | null;
+    options: string[];
+    builtin: boolean;
+}
+/**
+ * Read the settings out of a `/v1/appearance` body. Defensive: an older server
+ * (no `captchaFlows`) or a malformed body yields empty settings, so the
+ * components behave exactly as they did before these settings existed.
+ */
+export declare function instanceSettingsFrom(body: unknown): InstanceSettings;
+/**
+ * Fetch the instance's public settings (`GET /v1/appearance`). Null when the
+ * server can't be reached or answers with an error — the components then fall
+ * back to their defaults, and the server still enforces every gate.
+ */
+export declare function fetchInstanceSettings(client: FapiClient): Promise<InstanceSettings | null>;
+/**
+ * Split a create-account form's values into the `startSignUp` input: `email` and
+ * `password` are the credentials, everything else is a configured sign-up field
+ * (blank optional fields are dropped, so the server never sees empty strings).
+ * `consent` is the legal-consent tick (send `true` when no agreement is
+ * required — the server only enforces it when the instance opts in).
+ */
+export declare function toSignUpInput(values: Record<string, string>, consent: boolean, captchaToken?: string | null): {
+    email: string;
+    password: string;
+    fields: Record<string, string>;
+    consent: boolean;
+    captchaToken?: string;
+};

package/dist/instance-settings.js

@@ -0,0 +1,74 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.instanceSettingsFrom = instanceSettingsFrom;
+exports.fetchInstanceSettings = fetchInstanceSettings;
+exports.toSignUpInput = toSignUpInput;
+const NO_LEGAL = { termsUrl: null, privacyUrl: null, required: false };
+const isRecord = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+/**
+ * Read the settings out of a `/v1/appearance` body. Defensive: an older server
+ * (no `captchaFlows`) or a malformed body yields empty settings, so the
+ * components behave exactly as they did before these settings existed.
+ */
+function instanceSettingsFrom(body) {
+    const root = isRecord(body) ? body : {};
+    const appearance = isRecord(root.appearance) ? root.appearance : {};
+    const captchaFlows = {};
+    if (isRecord(root.captchaFlows)) {
+        for (const key of ['signUp', 'signIn', 'guest', 'passwordReset']) {
+            const flow = root.captchaFlows[key];
+            if (!isRecord(flow))
+                continue;
+            captchaFlows[key] = {
+                enabled: flow.enabled === true,
+                ...(typeof flow.provider === 'string' ? { provider: flow.provider } : {}),
+                ...(typeof flow.siteKey === 'string' ? { siteKey: flow.siteKey } : {}),
+                ...(flow.widget === 'invisible' || flow.widget === 'managed' || flow.widget === 'visible'
+                    ? { widget: flow.widget }
+                    : {}),
+            };
+        }
+    }
+    const signUpFields = Array.isArray(appearance.signUpFields)
+        ? appearance.signUpFields.filter((f) => isRecord(f) && typeof f.key === 'string' && typeof f.label === 'string')
+        : [];
+    const legalRaw = isRecord(appearance.legal) ? appearance.legal : null;
+    const legal = legalRaw
+        ? {
+            termsUrl: typeof legalRaw.termsUrl === 'string' ? legalRaw.termsUrl : null,
+            privacyUrl: typeof legalRaw.privacyUrl === 'string' ? legalRaw.privacyUrl : null,
+            required: legalRaw.required === true,
+        }
+        : NO_LEGAL;
+    return { captchaFlows, signUpFields, legal };
+}
+/**
+ * Fetch the instance's public settings (`GET /v1/appearance`). Null when the
+ * server can't be reached or answers with an error — the components then fall
+ * back to their defaults, and the server still enforces every gate.
+ */
+async function fetchInstanceSettings(client) {
+    try {
+        const response = await client.get('/v1/appearance');
+        return response.ok ? instanceSettingsFrom(response.data) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Split a create-account form's values into the `startSignUp` input: `email` and
+ * `password` are the credentials, everything else is a configured sign-up field
+ * (blank optional fields are dropped, so the server never sees empty strings).
+ * `consent` is the legal-consent tick (send `true` when no agreement is
+ * required — the server only enforces it when the instance opts in).
+ */
+function toSignUpInput(values, consent, captchaToken) {
+    const { email = '', password = '', ...rest } = values;
+    const fields = {};
+    for (const [key, value] of Object.entries(rest))
+        if (value)
+            fields[key] = value;
+    return { email, password, fields, consent, ...(captchaToken ? { captchaToken } : {}) };
+}
+//# sourceMappingURL=instance-settings.js.map

package/dist/instance-settings.js.map

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

package/dist/popup-channel.d.ts

@@ -0,0 +1,95 @@
+/**
+ * §oauth popup mode — the same-origin hand-back for a popup whose
+ * `window.opener` was severed.
+ *
+ * When the page that opens the sign-in popup sends a restrictive
+ * Cross-Origin-Opener-Policy (`same-origin`), the browser puts the cross-origin
+ * popup in another browsing-context group: `popup.closed` reads `true` to the
+ * opener almost at once and `window.opener` is `null` inside the popup, so the
+ * Frontend API's `postMessage` can never arrive. The Frontend API then sends the
+ * popup back to the OPENER's own page with the result in the URL fragment
+ * (`#atlas_popup_result=…`, never the query). That page runs the SDK, which:
+ *
+ *   1. reads and scrubs the fragment ({@link completeOAuthPopupLanding}),
+ *   2. relays the result to the opener over
+ *      `BroadcastChannel('atlas:oauth:<nonce>')` (a `localStorage` `storage`
+ *      event where BroadcastChannel is missing) — both are same-origin, so
+ *      they connect where `window.opener` cannot,
+ *   3. closes the popup once the opener acknowledges.
+ *
+ * Nothing here carries a token: the result is the same one-time ticket (or
+ * continuation) the redirect flow puts in its URL, and the opener exchanges it.
+ */
+/** The window name {@link startOauthPopup} opens the popup with. */
+export declare const OAUTH_POPUP_WINDOW_NAME = "atlas:oauth";
+/** The fragment key the Frontend API lands the popup result in. */
+export declare const POPUP_RESULT_FRAGMENT = "atlas_popup_result";
+/** The channel a page that finished sign-in inside the popup announces on. */
+export declare const POPUP_SIGNAL_CHANNEL = "atlas:oauth";
+/** The per-flow channel: `atlas:oauth:<nonce>`. */
+export declare function popupChannelName(nonce: string): string;
+/** A fresh base64url channel nonce (22 characters). */
+export declare function createPopupNonce(): string;
+/** The messages on the popup channels. */
+export type PopupRelayMessage = {
+    type: 'atlas:oauth:result';
+    id: string;
+    result: Record<string, unknown>;
+} | {
+    type: 'atlas:oauth:signed_in';
+    id: string;
+} | {
+    type: 'atlas:oauth:ack';
+    id: string;
+};
+/**
+ * Opener side: listen on the flow's channel (and the shared signal channel) for
+ * the popup's result. Every message is acknowledged so the popup can close.
+ * Returns the stop function.
+ */
+export declare function listenForPopupResult(nonce: string, handlers: {
+    /** The landing page relayed the Frontend API's result payload. */
+    onResult: (payload: Record<string, unknown>) => void;
+    /** A page in the popup finished the sign-in itself (cookies are set). */
+    onSignedIn?: () => void;
+}): () => void;
+/** The popup result the Frontend API put in a URL fragment, or null. */
+export declare function readPopupLanding(hash: string): {
+    nonce: string;
+    payload: Record<string, unknown>;
+} | null;
+/** What {@link completeOAuthPopupLanding} did with a landed popup result. */
+export interface PopupLanding {
+    /** The Frontend API's result payload (`type`, `ticket`, `attemptId`, …). */
+    payload: Record<string, unknown>;
+    /**
+     * True when the opener acknowledged the result: it completes the sign-in and
+     * this window is being closed. False when nobody was listening (the opener tab
+     * was closed, or is on another origin) — the caller should complete the
+     * sign-in on this page instead, exactly like a redirect.
+     */
+    delivered: boolean;
+}
+/**
+ * Popup side, run on startup: if this page is the landing of a severed popup
+ * (`#atlas_popup_result=…` in the URL — normally with `window.name ===
+ * 'atlas:oauth'`, though a browser may clear the name when the opener's COOP
+ * switched browsing-context groups, so the fragment alone is decisive), scrub
+ * the fragment, relay the result to the opener and close this window once the
+ * opener acknowledges. Returns null when this is not such a landing.
+ */
+export declare function completeOAuthPopupLanding(options?: {
+    win?: Window;
+    ackTimeoutMs?: number;
+}): Promise<PopupLanding | null>;
+/**
+ * Popup side, after a sign-in completed ON this page (the redirect flow ran in
+ * the popup — e.g. an SDK or provider path without the channel): when this is
+ * the Atlas popup window, tell the waiting opener and close. It closes only when
+ * an opener is there to take over (it acknowledged, or `window.opener` is live),
+ * never stranding a user whose opener tab is gone. Resolves whether it closed.
+ */
+export declare function closeOAuthPopupAfterSignIn(options?: {
+    win?: Window;
+    ackTimeoutMs?: number;
+}): Promise<boolean>;

package/dist/popup-channel.js

@@ -0,0 +1,231 @@
+"use strict";
+/**
+ * §oauth popup mode — the same-origin hand-back for a popup whose
+ * `window.opener` was severed.
+ *
+ * When the page that opens the sign-in popup sends a restrictive
+ * Cross-Origin-Opener-Policy (`same-origin`), the browser puts the cross-origin
+ * popup in another browsing-context group: `popup.closed` reads `true` to the
+ * opener almost at once and `window.opener` is `null` inside the popup, so the
+ * Frontend API's `postMessage` can never arrive. The Frontend API then sends the
+ * popup back to the OPENER's own page with the result in the URL fragment
+ * (`#atlas_popup_result=…`, never the query). That page runs the SDK, which:
+ *
+ *   1. reads and scrubs the fragment ({@link completeOAuthPopupLanding}),
+ *   2. relays the result to the opener over
+ *      `BroadcastChannel('atlas:oauth:<nonce>')` (a `localStorage` `storage`
+ *      event where BroadcastChannel is missing) — both are same-origin, so
+ *      they connect where `window.opener` cannot,
+ *   3. closes the popup once the opener acknowledges.
+ *
+ * Nothing here carries a token: the result is the same one-time ticket (or
+ * continuation) the redirect flow puts in its URL, and the opener exchanges it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.POPUP_SIGNAL_CHANNEL = exports.POPUP_RESULT_FRAGMENT = exports.OAUTH_POPUP_WINDOW_NAME = void 0;
+exports.popupChannelName = popupChannelName;
+exports.createPopupNonce = createPopupNonce;
+exports.listenForPopupResult = listenForPopupResult;
+exports.readPopupLanding = readPopupLanding;
+exports.completeOAuthPopupLanding = completeOAuthPopupLanding;
+exports.closeOAuthPopupAfterSignIn = closeOAuthPopupAfterSignIn;
+const tab_election_1 = require("./tab-election");
+/** The window name {@link startOauthPopup} opens the popup with. */
+exports.OAUTH_POPUP_WINDOW_NAME = 'atlas:oauth';
+/** The fragment key the Frontend API lands the popup result in. */
+exports.POPUP_RESULT_FRAGMENT = 'atlas_popup_result';
+/** The channel a page that finished sign-in inside the popup announces on. */
+exports.POPUP_SIGNAL_CHANNEL = 'atlas:oauth';
+/** The per-flow channel: `atlas:oauth:<nonce>`. */
+function popupChannelName(nonce) {
+    return `${exports.POPUP_SIGNAL_CHANNEL}:${nonce}`;
+}
+/** A fresh base64url channel nonce (22 characters). */
+function createPopupNonce() {
+    const bytes = new Uint8Array(16);
+    const c = globalThis.crypto;
+    if (c?.getRandomValues)
+        c.getRandomValues(bytes);
+    else
+        for (let i = 0; i < bytes.length; i++)
+            bytes[i] = Math.floor(Math.random() * 256);
+    let bin = '';
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function isRelayMessage(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const m = value;
+    if (typeof m.id !== 'string')
+        return false;
+    if (m.type === 'atlas:oauth:result')
+        return !!m.result && typeof m.result === 'object';
+    return m.type === 'atlas:oauth:signed_in' || m.type === 'atlas:oauth:ack';
+}
+function openChannel(name) {
+    try {
+        return (0, tab_election_1.broadcastChannel)(name) ?? (0, tab_election_1.storageChannel)(name);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Post `message` on `name` and resolve whether anyone acknowledged it within
+ * `timeoutMs`.
+ */
+function relay(name, message, timeoutMs) {
+    const channel = openChannel(name);
+    if (!channel)
+        return Promise.resolve(false);
+    const id = createPopupNonce();
+    return new Promise((resolve) => {
+        let done = false;
+        const finish = (acked) => {
+            if (done)
+                return;
+            done = true;
+            clearTimeout(timer);
+            unsubscribe();
+            channel.close();
+            resolve(acked);
+        };
+        const unsubscribe = channel.subscribe((m) => {
+            if (isRelayMessage(m) && m.type === 'atlas:oauth:ack' && m.id === id)
+                finish(true);
+        });
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        try {
+            channel.post({ ...message, id });
+        }
+        catch {
+            finish(false);
+        }
+    });
+}
+/**
+ * Opener side: listen on the flow's channel (and the shared signal channel) for
+ * the popup's result. Every message is acknowledged so the popup can close.
+ * Returns the stop function.
+ */
+function listenForPopupResult(nonce, handlers) {
+    const flow = openChannel(popupChannelName(nonce));
+    const signal = handlers.onSignedIn ? openChannel(exports.POPUP_SIGNAL_CHANNEL) : null;
+    const unsubscribers = [];
+    if (flow) {
+        unsubscribers.push(flow.subscribe((m) => {
+            if (!isRelayMessage(m) || m.type !== 'atlas:oauth:result')
+                return;
+            flow.post({ type: 'atlas:oauth:ack', id: m.id });
+            handlers.onResult(m.result);
+        }));
+    }
+    if (signal) {
+        unsubscribers.push(signal.subscribe((m) => {
+            if (!isRelayMessage(m) || m.type !== 'atlas:oauth:signed_in')
+                return;
+            signal.post({ type: 'atlas:oauth:ack', id: m.id });
+            handlers.onSignedIn?.();
+        }));
+    }
+    return () => {
+        for (const u of unsubscribers)
+            u();
+        flow?.close();
+        signal?.close();
+    };
+}
+/** The popup result the Frontend API put in a URL fragment, or null. */
+function readPopupLanding(hash) {
+    if (!hash || hash.length < 2)
+        return null;
+    const raw = new URLSearchParams(hash.replace(/^#/, '')).get(exports.POPUP_RESULT_FRAGMENT);
+    if (!raw)
+        return null;
+    try {
+        const b64 = raw.replace(/-/g, '+').replace(/_/g, '/');
+        const bin = atob(b64 + '='.repeat((4 - (b64.length % 4)) % 4));
+        const bytes = Uint8Array.from(bin, (ch) => ch.charCodeAt(0));
+        const payload = JSON.parse(new TextDecoder().decode(bytes));
+        if (!payload || typeof payload !== 'object')
+            return null;
+        const p = payload;
+        if (p.v !== 1 || typeof p.n !== 'string' || !p.n)
+            return null;
+        if (typeof p.type !== 'string' || !p.type.startsWith('atlas:oauth:'))
+            return null;
+        return { nonce: p.n, payload: p };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Popup side, run on startup: if this page is the landing of a severed popup
+ * (`#atlas_popup_result=…` in the URL — normally with `window.name ===
+ * 'atlas:oauth'`, though a browser may clear the name when the opener's COOP
+ * switched browsing-context groups, so the fragment alone is decisive), scrub
+ * the fragment, relay the result to the opener and close this window once the
+ * opener acknowledges. Returns null when this is not such a landing.
+ */
+async function completeOAuthPopupLanding(options = {}) {
+    const win = options.win ?? (typeof window !== 'undefined' ? window : undefined);
+    if (!win)
+        return null;
+    const landing = readPopupLanding(win.location.hash);
+    if (!landing)
+        return null;
+    // Scrub first: a reload, the back button or a copied URL must never replay it.
+    try {
+        win.history.replaceState(win.history.state, '', win.location.href.split('#')[0]);
+    }
+    catch {
+        /* a sandboxed history; the ticket is single-use regardless */
+    }
+    // We ARE the Atlas popup, whatever the browser did to the name.
+    try {
+        win.name = exports.OAUTH_POPUP_WINDOW_NAME;
+    }
+    catch {
+        /* ignore */
+    }
+    const delivered = await relay(popupChannelName(landing.nonce), { type: 'atlas:oauth:result', result: landing.payload }, options.ackTimeoutMs ?? 1_500);
+    if (delivered)
+        closeWindow(win);
+    return { payload: landing.payload, delivered };
+}
+/**
+ * Popup side, after a sign-in completed ON this page (the redirect flow ran in
+ * the popup — e.g. an SDK or provider path without the channel): when this is
+ * the Atlas popup window, tell the waiting opener and close. It closes only when
+ * an opener is there to take over (it acknowledged, or `window.opener` is live),
+ * never stranding a user whose opener tab is gone. Resolves whether it closed.
+ */
+async function closeOAuthPopupAfterSignIn(options = {}) {
+    const win = options.win ?? (typeof window !== 'undefined' ? window : undefined);
+    if (!win || win.name !== exports.OAUTH_POPUP_WINDOW_NAME)
+        return false;
+    const acked = await relay(exports.POPUP_SIGNAL_CHANNEL, { type: 'atlas:oauth:signed_in' }, options.ackTimeoutMs ?? 1_500);
+    let hasOpener = false;
+    try {
+        hasOpener = !!win.opener && !win.opener.closed;
+    }
+    catch {
+        hasOpener = false;
+    }
+    if (!acked && !hasOpener)
+        return false;
+    closeWindow(win);
+    return true;
+}
+function closeWindow(win) {
+    try {
+        win.close();
+    }
+    catch {
+        /* the browser refused; nothing else to do */
+    }
+}
+//# sourceMappingURL=popup-channel.js.map

package/dist/popup-channel.js.map

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

package/dist/redirect.d.ts

@@ -59,6 +59,12 @@ export interface PopupOutcome {
  * `postMessage` on the page can never drive the flow.
  */
 export declare function parseOAuthPopupMessage(eventOrigin: string, expectedOrigin: string, data: unknown): PopupOutcome | null;
+/**
+ * Pure: map one of the Frontend API's `atlas:oauth:*` result payloads (from a
+ * `postMessage`, or relayed from a severed popup's landing page) to an outcome,
+ * or null when it is not one.
+ */
+export declare function mapOAuthPopupPayload(data: unknown): PopupOutcome | null;
 export interface OAuthPopupHandlers {
     onOpen?: () => void;
     onComplete?: (r: {
@@ -68,23 +74,66 @@ export interface OAuthPopupHandlers {
     onError?: (code: string) => void;
     /** Fired when the popup couldn't open; the caller should navigate to the URL. */
     onBlockedFallback?: (authorizationUrl: string) => void;
+    /**
+     * Fired when the popup's link to this page was severed right after opening
+     * (this page, or the provider, sends a Cross-Origin-Opener-Policy): the popup
+     * still works, but closing it can no longer be noticed, so the flow keeps
+     * waiting — up to 5 minutes — for its result. A good moment to show "Finish
+     * signing in in the popup window" with a cancel button that aborts `signal`.
+     */
+    onSevered?: () => void;
 }
 export interface PopupStartResult extends PopupOutcome {
     /** True when the popup was blocked — the caller falls back to a full redirect. */
     blocked?: boolean;
     authorizationUrl?: string;
+    /**
+     * Set (with `error: 'popup_closed'`) when the popup closed without posting a
+     * result but the Frontend API now reports a signed-in session — e.g. the
+     * browser severed `window.opener`, so the popup finished the sign-in itself.
+     * The caller should re-boot its session state rather than treat it as a
+     * cancel.
+     */
+    sessionDetected?: boolean;
+    /** True when the popup's opener link was severed (see `onSevered`). */
+    severed?: boolean;
+}
+/** Input to {@link startOauthPopup}. */
+export interface OAuthPopupInput {
+    provider: string;
+    /**
+     * Where the redirect flow would return to — normally the current page. A
+     * popup whose opener link is severed lands back here (result in the
+     * fragment), so it should be a page on THIS origin that runs the SDK.
+     */
+    redirectUrl: string;
+    /** Abort to give up on the popup (settles as `popup_closed`). */
+    signal?: AbortSignal;
 }
+/** `popup.closed` this soon after opening means the opener link was severed, not a user close. */
+export declare const POPUP_SEVERED_WINDOW_MS = 1500;
+/** How long a severed popup is waited for before it counts as cancelled. */
+export declare const POPUP_SEVERED_TIMEOUT_MS: number;
 /**
  * Start a POPUP OAuth sign-in (GSI-style). Opens the provider authorize URL in a
  * popup and resolves when the callback posts back the one-time ticket (complete),
  * an error, or a continuation. Falls back to a full redirect when the popup is
  * blocked — resolves `{ blocked:true, authorizationUrl }` and the caller
  * navigates there, so it is always safe to enable. Browser-only.
+ *
+ * The result arrives by `postMessage` from the Frontend API, or — when a
+ * Cross-Origin-Opener-Policy severed the popup from this page — relayed over
+ * `BroadcastChannel('atlas:oauth:<nonce>')` by the SDK on the page the popup
+ * lands on (see ./popup-channel). Cancel semantics:
+ *   - the popup closes after the first {@link POPUP_SEVERED_WINDOW_MS}: the user
+ *     closed it — one final session probe, then `popup_closed`;
+ *   - `popup.closed` reads true within that window: the link was severed (the
+ *     popup is very much open). Keep waiting for the relayed result, probing
+ *     the session with back-off, and settle as `popup_closed` only after
+ *     {@link POPUP_SEVERED_TIMEOUT_MS}, an explicit error/cancel result,
+ *     `input.signal` aborting, or a newer popup flow starting.
  */
-export declare function startOauthPopup(client: FapiClient, input: {
-    provider: string;
-    redirectUrl: string;
-}, handlers?: OAuthPopupHandlers): Promise<PopupStartResult>;
+export declare function startOauthPopup(client: FapiClient, input: OAuthPopupInput, handlers?: OAuthPopupHandlers): Promise<PopupStartResult>;
 /**
  * Read Atlas's redirect params from a query string (`window.location.search`).
  *