brightspace-mcp-server 1.6.2 → 2.0.0

package/build/auth/auth-lock.js

@@ -0,0 +1,114 @@
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { hostname } from "node:os";
+import { randomUUID } from "node:crypto";
+export class AuthenticationInProgressError extends Error {
+    code = "AUTH_IN_PROGRESS";
+    constructor() {
+        super("Authentication already in progress. Retry after the current authentication finishes.");
+        this.name = "AuthenticationInProgressError";
+    }
+}
+async function readOwner(lockPath) {
+    try {
+        const owner = JSON.parse(await fs.readFile(path.join(lockPath, "owner.json"), "utf8"));
+        if (Number.isSafeInteger(owner.pid) && owner.pid > 0 && typeof owner.host === "string" && typeof owner.nonce === "string")
+            return owner;
+    }
+    catch {
+        // An incomplete or unknown lock is not proof that its owner is gone.
+    }
+    return undefined;
+}
+function isDead(owner) {
+    // Session directories are local-only. DHCP can change the host's name
+    // without changing this process table, so only PID liveness decides.
+    try {
+        process.kill(owner.pid, 0);
+        return false;
+    }
+    catch (error) {
+        return error.code === "ESRCH";
+    }
+}
+/** Remove only our fixed metadata names, after the directory was retired. */
+async function cleanRetired(lockPath) {
+    await fs.unlink(path.join(lockPath, "owner.json")).catch(() => { });
+    await cleanChild(path.join(lockPath, "reclaim.lock"));
+    await fs.rmdir(lockPath).catch(() => { });
+}
+async function cleanChild(childPath) {
+    try {
+        if ((await fs.lstat(childPath)).isDirectory())
+            await cleanRetired(childPath);
+    }
+    catch { /* Already absent. */ }
+}
+class Lease {
+    directory;
+    owner;
+    constructor(directory, owner) {
+        this.directory = directory;
+        this.owner = owner;
+    }
+    async release() {
+        const current = await readOwner(this.directory);
+        if (current?.nonce !== this.owner.nonce)
+            return;
+        const retired = `${this.directory}.released.${this.owner.nonce}`;
+        await fs.rename(this.directory, retired);
+        await cleanRetired(retired);
+    }
+}
+/** Acquire a process-shared lock without waiting or relying on its age. */
+export async function acquireProcessLock(lockPath) {
+    await fs.mkdir(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+    const lease = await acquireLease(lockPath, 0);
+    return () => lease.release();
+}
+async function acquireLease(lockPath, depth) {
+    if (depth > 16)
+        throw new AuthenticationInProgressError();
+    const owner = { pid: process.pid, host: hostname(), nonce: randomUUID() };
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        try {
+            await fs.mkdir(lockPath, { mode: 0o700 });
+            try {
+                await fs.writeFile(path.join(lockPath, "owner.json"), JSON.stringify(owner), { flag: "wx", mode: 0o600 });
+            }
+            catch (error) {
+                await fs.rmdir(lockPath).catch(() => { });
+                throw error;
+            }
+            return new Lease(lockPath, owner);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                throw new AuthenticationInProgressError();
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const stale = await readOwner(lockPath);
+        if (!stale || !isDead(stale))
+            throw new AuthenticationInProgressError();
+        // Recovery gets its own process lock within the stale directory. If a
+        // recovering process crashes, the same dead-owner rules recover its lock.
+        // Keep this claim in the directory during rename to serialize contenders.
+        const claim = await acquireLease(path.join(lockPath, "reclaim.lock"), depth + 1);
+        try {
+            const current = await readOwner(lockPath);
+            if (current?.nonce !== stale.nonce || !isDead(current))
+                throw new AuthenticationInProgressError();
+            const retired = `${lockPath}.stale.${owner.nonce}`;
+            await fs.rename(lockPath, retired);
+            claim.directory = path.join(retired, "reclaim.lock");
+            await claim.release();
+            await cleanRetired(retired);
+        }
+        finally {
+            await claim.release();
+        }
+    }
+    throw new AuthenticationInProgressError();
+}
+//# sourceMappingURL=auth-lock.js.map

package/build/auth/auth-lock.js.map

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

package/build/auth/auth-runner.d.ts

@@ -3,23 +3,33 @@
  * Copyright (c) 2026 Rohan Muppa. All rights reserved.
  * Licensed under MIT — see LICENSE file for details.
  */
+import { AuthError } from "../utils/errors.js";
+export type AuthFailureKind = "busy" | "cooldown" | "unsupported" | "secureStorage" | "transport" | "timeout" | "failed";
+export declare class AuthProcessError extends AuthError {
+    readonly kind: AuthFailureKind;
+    constructor(kind: AuthFailureKind, message: string);
+}
+export interface AuthRunnerOptions {
+    timeoutMs?: number;
+    onProgress?: (line: string) => void;
+}
 /**
  * Launches the brightspace-auth CLI as a child process to
  * re-authenticate when the current session has expired.
  *
- * The child process inherits the parent's environment (so .env credentials
- * are available via dotenv in the auth CLI) and runs with the project root
- * as CWD (so dotenv can find the .env file).
+ * The child inherits the parent's resolved environment and working directory,
+ * so both processes read the same account configuration and .env file.
  */
 export declare class AuthRunner {
     private running;
     private readonly scriptPath;
-    private readonly projectRoot;
-    constructor();
+    private readonly timeoutMs;
+    private readonly onProgress?;
+    constructor(options?: AuthRunnerOptions);
     /**
      * Spawn the auth CLI and wait for it to complete.
-     * Returns true if authentication succeeded, false otherwise.
-     * Prevents concurrent auth attempts via a simple mutex.
+     * Returns true on success and throws a useful error on failure.
+     * Prevents concurrent attempts within this MCP process.
      */
     run(): Promise<boolean>;
 }

package/build/auth/auth-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-runner.d.ts","sourceRoot":"","sources":["../../src/auth/auth-runner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA4CH;;;;;;;GAOG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;;IASrC;;;;OAIG;IACG,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC;CAwD9B"}
+{"version":3,"file":"auth-runner.d.ts","sourceRoot":"","sources":["../../src/auth/auth-runner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAW/C,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,UAAU,GAAG,aAAa,GAAG,eAAe,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAEzH,qBAAa,gBAAiB,SAAQ,SAAS;aACjB,IAAI,EAAE,eAAe;gBAArB,IAAI,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM;CAInE;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAkDD;;;;;;GAMG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAyB;gBAEzC,OAAO,GAAE,iBAAsB;IAQ3C;;;;OAIG;IACG,GAAG,IAAI,OAAO,CAAC,OAAO,CAAC;CAyG9B"}

package/build/auth/auth-runner.js

@@ -3,17 +3,46 @@
  * Copyright (c) 2026 Rohan Muppa. All rights reserved.
  * Licensed under MIT — see LICENSE file for details.
  */
-import { spawn } from "node:child_process";
+import { spawn, execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { log } from "../utils/logger.js";
+import { AuthError } from "../utils/errors.js";
 /**
  * Timeout for the auth process. It has to outlast the child's own MFA wait,
  * which is five minutes: a person has to find their phone, unlock it, and read
  * a number off the screen. A shorter parent budget would kill the child in the
  * middle of a sign-in the user was still completing.
  */
-const AUTH_TIMEOUT_MS = 6 * 60 * 1000; // 6 minutes
+const AUTH_TIMEOUT_MS = 8 * 60 * 1000;
+const KILL_GRACE_MS = 5000;
+export class AuthProcessError extends AuthError {
+    kind;
+    constructor(kind, message) {
+        super(message);
+        this.kind = kind;
+        this.name = "AuthProcessError";
+    }
+}
+/** Chromium can lead a separate process group, so a forced stop needs its PID. */
+function descendantPids(parentPid) {
+    const rows = execFileSync("ps", ["-eo", "pid=,ppid="], {
+        encoding: "utf8", timeout: 1000,
+    }).trim().split("\n").map(line => line.trim().split(/\s+/).map(Number));
+    const descendants = [];
+    const visited = new Set([parentPid]);
+    const visit = (parent) => {
+        for (const [pid, ppid] of rows) {
+            if (ppid === parent && Number.isInteger(pid) && pid > 1 && !visited.has(pid)) {
+                visited.add(pid);
+                visit(pid);
+                descendants.push(pid);
+            }
+        }
+    };
+    visit(parentPid);
+    return descendants;
+}
 /**
  * Forward a child stream to the server log, one line at a time.
  *
@@ -45,67 +74,134 @@ function forwardLines(stream, emit) {
  * Launches the brightspace-auth CLI as a child process to
  * re-authenticate when the current session has expired.
  *
- * The child process inherits the parent's environment (so .env credentials
- * are available via dotenv in the auth CLI) and runs with the project root
- * as CWD (so dotenv can find the .env file).
+ * The child inherits the parent's resolved environment and working directory,
+ * so both processes read the same account configuration and .env file.
  */
 export class AuthRunner {
     running = false;
     scriptPath;
-    projectRoot;
-    constructor() {
+    timeoutMs;
+    onProgress;
+    constructor(options = {}) {
         // Resolve paths relative to this file's compiled location (build/auth/auth-runner.js)
         const thisDir = path.dirname(fileURLToPath(import.meta.url));
         this.scriptPath = path.resolve(thisDir, "..", "auth-cli.js");
-        this.projectRoot = path.resolve(thisDir, "..", "..");
+        this.timeoutMs = options.timeoutMs ?? AUTH_TIMEOUT_MS;
+        this.onProgress = options.onProgress;
     }
     /**
      * Spawn the auth CLI and wait for it to complete.
-     * Returns true if authentication succeeded, false otherwise.
-     * Prevents concurrent auth attempts via a simple mutex.
+     * Returns true on success and throws a useful error on failure.
+     * Prevents concurrent attempts within this MCP process.
      */
     async run() {
         if (this.running) {
-            log("DEBUG", "Auth already running, skipping duplicate attempt");
-            return false;
+            throw new AuthProcessError("busy", "Authentication already in progress. Complete the existing attempt, then retry.");
         }
         this.running = true;
         try {
             log("INFO", "Auto-launching brightspace-auth...");
-            return await new Promise((resolve) => {
+            return await new Promise((resolve, reject) => {
                 const child = spawn(process.execPath, // use the same Node binary
-                [this.scriptPath], {
-                    cwd: this.projectRoot,
+                [this.scriptPath, "--automatic"], {
+                    cwd: process.cwd(),
                     env: { ...process.env },
                     stdio: ["ignore", "pipe", "pipe"],
+                    detached: process.platform !== "win32",
                 });
                 let timedOut = false;
+                let settled = false;
+                let killTimer;
+                const kill = (signal) => {
+                    try {
+                        if (child.pid && process.platform === "win32") {
+                            execFileSync("taskkill", ["/pid", String(child.pid), "/t", "/f"], {
+                                stdio: "ignore", timeout: 5000,
+                            });
+                        }
+                        else if (child.pid) {
+                            if (signal === "SIGKILL") {
+                                try {
+                                    for (const pid of descendantPids(child.pid)) {
+                                        try {
+                                            process.kill(pid, "SIGKILL");
+                                        }
+                                        catch { /* Already exited. */ }
+                                    }
+                                }
+                                catch { /* Still terminate the owned process group if ps is unavailable. */ }
+                            }
+                            process.kill(-child.pid, signal);
+                        }
+                        else
+                            child.kill(signal);
+                    }
+                    catch {
+                        // The child may already have exited between close and cleanup.
+                    }
+                };
+                const onExit = () => kill("SIGTERM");
+                process.once("exit", onExit);
+                const finish = (error) => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    clearTimeout(timer);
+                    if (killTimer)
+                        clearTimeout(killTimer);
+                    process.off("exit", onExit);
+                    if (error)
+                        reject(error);
+                    else
+                        resolve(true);
+                };
                 const timer = setTimeout(() => {
                     timedOut = true;
-                    child.kill("SIGTERM");
-                }, AUTH_TIMEOUT_MS);
-                forwardLines(child.stderr, (line) => log("INFO", line));
+                    kill("SIGTERM");
+                    killTimer = setTimeout(() => {
+                        kill("SIGKILL");
+                        finish(new AuthProcessError("timeout", "Authentication timed out. Run brightspace-auth to try again."));
+                    }, KILL_GRACE_MS);
+                }, this.timeoutMs);
+                forwardLines(child.stderr, (line) => {
+                    log("INFO", line);
+                    try {
+                        this.onProgress?.(line);
+                    }
+                    catch { /* Logging must not interrupt authentication. */ }
+                });
                 // Piped and drained rather than ignored: a full stdout pipe would
                 // block the child mid-login.
                 forwardLines(child.stdout, (line) => log("DEBUG", line));
                 child.on("error", (error) => {
-                    clearTimeout(timer);
+                    if (settled)
+                        return;
                     log("ERROR", "Auto-auth process failed", error.message);
-                    resolve(false);
+                    kill("SIGKILL");
+                    finish(new AuthProcessError("failed", "Could not start authentication. Run brightspace-auth for details."));
                 });
                 child.on("close", (code) => {
-                    clearTimeout(timer);
+                    if (settled)
+                        return;
                     if (timedOut) {
-                        log("ERROR", `Auto-auth timed out after ${AUTH_TIMEOUT_MS / 60000} minutes`);
-                        resolve(false);
+                        kill("SIGKILL");
+                        finish(new AuthProcessError("timeout", "Authentication timed out. Run brightspace-auth to try again."));
                     }
                     else if (code === 0) {
                         log("INFO", "Auto-auth completed successfully");
-                        resolve(true);
+                        finish();
                     }
                     else {
-                        log("ERROR", `Auto-auth process failed with exit code ${code}`);
-                        resolve(false);
+                        const failures = {
+                            2: ["busy", "Authentication already in progress in another process. Complete that attempt, then retry."],
+                            3: ["cooldown", "Automatic MFA is paused after an unsuccessful attempt. Run brightspace-auth to retry immediately."],
+                            4: ["unsupported", "This identity provider cannot complete headless authentication. See the authentication logs."],
+                            5: ["secureStorage", "The native credential store is unavailable or locked. Unlock it and retry."],
+                            6: ["transport", "Brightspace authentication is temporarily unavailable because of a network or server failure. Your saved session was preserved. Try again later."],
+                        };
+                        const [kind, message] = failures[code ?? -1] ?? ["failed", "Authentication failed. Run brightspace-auth to try again."];
+                        kill("SIGKILL");
+                        finish(new AuthProcessError(kind, message));
                     }
                 });
             });

package/build/auth/auth-runner.js.map

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

package/build/auth/browser-auth.d.ts

@@ -1,44 +1,27 @@
 /**
- * Purdue Brightspace MCP Server
+ * Brightspace MCP Server
  * Copyright (c) 2026 Rohan Muppa. All rights reserved.
- * Licensed under MIT — see LICENSE file for details.
+ * Licensed under MIT: see LICENSE file for details.
  */
 import type { AppConfig, TokenData } from "../types/index.js";
+export declare class BrowserAuthTransportError extends Error {
+    readonly code = "AUTH_TRANSPORT";
+    constructor(message: string, options?: ErrorOptions);
+}
+export interface AuthenticateOptions {
+    automatic?: boolean;
+    /** Persist the token before releasing the shared authentication lock. */
+    onAuthenticated?: (token: TokenData) => Promise<void>;
+}
 export declare class BrowserAuth {
     private config;
     private ssoFlow;
+    private readonly stateStore;
+    private readonly cooldown;
     constructor(config: AppConfig);
-    /**
-     * Detect if running inside WSL (Windows Subsystem for Linux) or Docker.
-     * These environments require --no-sandbox for Chromium to launch.
-     */
     private static isWSLOrDocker;
-    /**
-     * Build Chromium launch args based on the current platform and environment.
-     */
-    private static buildChromiumArgs;
-    /**
-     * Prevent Chrome for Testing from SIGTRAP'ing on launch on macOS (issue #10).
-     *
-     * Three layers, all idempotent and cheap:
-     *   1. ApplePersistenceIgnoreState — disables NSPersistentUIRestorer's crash-prompt
-     *      modal, which Chrome for Testing's AppKit bridge cannot handle.
-     *   2. IIO_LaunchInfo=0 — resets LaunchServices' per-app crash counter so macOS
-     *      stops triggering the recovery pathway in the first place.
-     *   3. Nuke the Cocoa saved-application-state bundle — if it exists, AppKit tries
-     *      to replay window state during launch and can crash the browser process.
-     *
-     * Runs before every launch. None of these are destructive to user data; Chrome
-     * for Testing is a disposable test profile.
-     */
-    private static applyMacOSCrashGuard;
-    /**
-     * Recovery step: the current browser-data profile is corrupted in a way that
-     * makes Chromium SIGTRAP during launch (issue #10). Move it aside so the next
-     * launch attempt gets a clean profile. Cheap — user just re-authenticates.
-     */
-    private quarantineBrowserDataDir;
-    authenticate(): Promise<TokenData>;
+    authenticate(options?: AuthenticateOptions): Promise<TokenData>;
+    private attemptAuthentication;
     /**
      * Run the token extraction strategy chain, cheapest to most invasive.
      * Each strategy validates against /users/whoami before returning.
@@ -50,23 +33,14 @@ export declare class BrowserAuth {
      * Returns true if the token is accepted by D2L, false otherwise.
      */
     private validateToken;
-    /**
-     * Set up passive network request listener to capture Bearer token.
-     * MUST be called BEFORE page.goto() to avoid race condition.
-     */
-    private setupTokenInterception;
-    /**
-     * Navigate to Brightspace and login if needed.
-     * Returns true if already authenticated (cookies valid), false if SSO login was performed.
-     */
+    /** Restore first, and only attempt credentials after a real sign-in is needed. */
     private navigateAndLogin;
-    /** Let the page finish loading, without letting a slow one fail the run. */
-    private settle;
     /**
      * Give the SSO chain a bounded window to finish with no human input.
      * Returns true only when the session proves itself live.
      */
     private awaitSilentSSO;
+    private hasCredentialPrompt;
     /**
      * A POSITIVE session check, never "the URL doesn't look like a login page".
      * Institutions bounce through intermediate SAML hops with a perfectly live
@@ -81,6 +55,8 @@ export declare class BrowserAuth {
     private clickSilentSurfaces;
     /** Visibility without the actionability wait, so a poll keeps its rhythm. */
     private isOnScreen;
+    /** Check each selector independently so a hidden earlier match cannot mask a visible one. */
+    private isAnyOnScreen;
     /**
      * Try to extract Bearer token from D2L's localStorage.
      * D2L stores API tokens in localStorage under "D2L.Fetch.Tokens".
@@ -109,29 +85,5 @@ export declare class BrowserAuth {
      * Constructs a cookie header string from d2lSessionVal and d2lSecureSessionVal.
      */
     private extractCookieToken;
-    /**
-     * Load previously saved storage state (cookies + localStorage).
-     * Workaround for Playwright bug #36139: session cookies don't persist in persistent context.
-     */
-    private loadStorageState;
-    private saveStorageState;
-    /**
-     * Launch browser with retry logic.
-     * Windows is prone to 180s launch timeouts (Playwright issue #22117) caused by
-     * lingering Chromium processes, antivirus interference, or resource contention.
-     * On timeout, we clear lock files and retry once.
-     */
-    private launchBrowserWithRetry;
-    /**
-     * Validate and remove stale Chromium lock files from the browser data directory.
-     * Playwright's persistent context uses Chromium's SingletonLock mechanism.
-     * If the browser is killed unexpectedly (antivirus, force close, crash),
-     * these lock files persist and block all future launch attempts.
-     *
-     * For SingletonLock (a symlink whose target is "hostname-pid"), we check
-     * whether the owning process is still alive before removing it. This avoids
-     * deleting a lock held by a legitimate running instance.
-     */
-    private validateAndClearLockFiles;
 }
 //# sourceMappingURL=browser-auth.d.ts.map

package/build/auth/browser-auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-auth.d.ts","sourceRoot":"","sources":["../../src/auth/browser-auth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AASH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AA2B9D,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,OAAO,CAAU;gBAEb,MAAM,EAAE,SAAS;IAK7B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAwB5B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAoBhC;;;;;;;;;;;;;OAaG;mBACkB,oBAAoB;IA8CzC;;;;OAIG;YACW,wBAAwB;IAoBhC,YAAY,IAAI,OAAO,CAAC,SAAS,CAAC;IA6KxC;;;;OAIG;YACW,eAAe;IAyD7B;;;OAGG;YACW,aAAa;IAmC3B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IA+B9B;;;OAGG;YACW,gBAAgB;IA8C9B,4EAA4E;YAC9D,MAAM;IAQpB;;;OAGG;YACW,cAAc;IAoB5B;;;;;OAKG;YACW,cAAc;IAiB5B;;;OAGG;YACW,mBAAmB;IAsCjC,6EAA6E;YAC/D,UAAU;IAIxB;;;OAGG;YACW,wBAAwB;IAyCtC;;;;;OAKG;YACW,sBAAsB;IAoCpC;;;;OAIG;YACW,eAAe;IAyC7B;;;OAGG;YACW,gBAAgB;IAgE9B;;;OAGG;YACW,kBAAkB;IAiChC;;;OAGG;YACW,gBAAgB;YA8FhB,gBAAgB;IAc9B;;;;;OAKG;YACW,sBAAsB;IA+DpC;;;;;;;;;OASG;YACW,yBAAyB;CAiExC"}
+{"version":3,"file":"browser-auth.d.ts","sourceRoot":"","sources":["../../src/auth/browser-auth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAuB9D,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,oBAAoB;gBACrB,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;CAIpD;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,yEAAyE;IACzE,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvD;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAoB;IAC/C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;gBAE5B,MAAM,EAAE,SAAS;IAO7B,OAAO,CAAC,MAAM,CAAC,aAAa;IAetB,YAAY,CAAC,OAAO,GAAE,mBAAwB,GAAG,OAAO,CAAC,SAAS,CAAC;YAgB3D,qBAAqB;IA+DnC;;;;OAIG;YACW,eAAe;IA0D7B;;;OAGG;YACW,aAAa;IA0B3B,kFAAkF;YACpE,gBAAgB;IAmD9B;;;OAGG;YACW,cAAc;YAmDd,mBAAmB;IAKjC;;;;;OAKG;YACW,cAAc;IAsB5B;;;OAGG;YACW,mBAAmB;IA0CjC,6EAA6E;YAC/D,UAAU;IAQxB,6FAA6F;YAC/E,aAAa;IAO3B;;;OAGG;YACW,wBAAwB;IAyCtC;;;;;OAKG;YACW,sBAAsB;IAoCpC;;;;OAIG;YACW,eAAe;IAoD7B;;;OAGG;YACW,gBAAgB;IAgE9B;;;OAGG;YACW,kBAAkB;CAiCjC"}